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Suite Rewards. 



CUst °mers! 



Infragistics - formed by the merger of Sheridan and ProtoView 



45 Award Winning Components included in UltraSuite™2.0: 



Grid 

>UltraCrid"2.0 

Office/Outlook- 
style Ul 

>Data Explorer™ 
>Outlook Bar 

Toolbars 

>UltraToolBars" 

Tree 

>ActiveTreeView" 



Calendaring 
& Dates 

>Calendar 

>DayView 

>TaskPad 

>DateEdit 

>TimeEdit 

Advanced DB 
Components 

>ComboBoxEx 
>DropDownEdit 
>HotLink 
>Spin 



>ComboBox 
>Listbox 

Tabs 

>ActiveTabs™ 

Data Input 

^Currency 

^Numeric 

>MaskEdit 

Resizers 

>Resizer 

>Resizer (works with 
non-client area) 



Advanced Ul 
Components 

>Scroll 

>Splash 

>Transition 

>Marquee 

>Picture 

>ProgressBar 

>Frame 

>Option 

>Command 

>Ribbon 

>Check 

>Splitter 



Recipient of seven VBPJ 2001 Readers' Choice Awards 



>Panel 
>Dial 

>Font Selector 

>Line3D 

>Multibutton 

>Shape3D 

>Text3D 

Utility Components 

>ScreenPrinter 
>PropertyBrowser 
HmageCombo 
>ColorCombo 
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t> TreeView object of 
the Data Explorer 

O UltraCrid control in 
the right pane of the 
Data Explorer 

ScheduleX controls 
in the bottom pane 
of the Data Explorer 

DayView control 
(part of ScheduleX) 

© Calendar control 
(part of ScheduleX) 

O TaskPad control 
(part of ScheduleX) 




UltraSuite 2.0 



We've combined our best-of-breed products into one positively jam-packed solution. Along with 
the familiar, easy-to-use interfaces of Microsoft Outlook, Microsoft Office and Windows Explorer, 
UltraSuite provides the most innovative grid available-UltraCrid2.0, and our UltraToolBars is 
loaded with functionality. With 45 controls, we've included everything necessary to create 
solutions that look great and run efficiently, faster than ever before. There's nothing like the 
productivity, flexibility and support of UltraSuite. 

You can really sweeten the deal-UltraSuite 2.0 is available with optional Subscription Service, or 
upgrade to the UltraSuite Enterprise Edition (includes subscription and guaranteed rapid response). 
Automatically receive all major upgrades (full version releases) and minor updates (enhancements 
and service releases) during your subscription period.* Make the most of your investment-you'll 
find the rewards can be "Suite". 



For detailed information, visit 
www.infragistics.com 

Download Free Trial Version! 
Order Online! or call 800-231-8588 



Infra gist ics 

Component powered infrastructure 



Copyright 200 1 Infragistics, Inc. All rights reserved. Infragistics, the Infragistics logo, UltraSuite, Data Explorer, AarveTreevtew, UltraCrid & UltraToolBars are trademarks of Infragisrjcs, Inc. 
All other trademarks or registered trademarks are the respective property of their owners. 



800-231-8588 infragistics.com 



© 2001 Microsoft Corporation. All rights reserved. Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. The names of actual companies and product? 




Web server farms have always been known for providing high 
application availability in a cost-efficient manner. Unfortunately, in 
the past they have also been known for manageability headaches. 
But no more: Microsoft Application Center 2000 now makes managing 
Web applications and groups of Web servers as simple as managing 
a single server. 

Part of the flexible Microsoft.NET Enterprise Server family, Application 
Center 2000 is built to be the heart of a "scale-out" infrastructure 
model. "Scaling out" is a flexible approach to scalability that involves 
deploying Web applications across multiple servers to distribute and 
handle the workload. 



Application Center 2000 makes scaling out easier, with unified 
Web application and server-farm management that simplifies tasks 

like cluster management and 



iindows" 



application deployment. Plus, it 
makes it easy to achieve capacity 
on demand through automatic 
replication of applications when 
you add servers or make changes 
to existing applications. But 

I I simplicity is not all you get: 

Application Center 2000 offers increased uptime through dynamic 
load balancing and by having no single point of failure. 

In sum, Application Center 2000 removes the hassle of managing multiple 
servers separately, while providing the availability and cost-efficiency of 
a "scale-out" model. Find out how to keep the odds in your favor: visit 
microsoft.com/applicationcenter Software for the Agile Business. 




Microsoft 



O Ad hoc end-user queries. 



© ...are a "point-and-click" away! 



© End-users simply choose conditions. 




O - via drop-downs... ...to quickly and easily set criteria. © Includes easy-to-use drop-down calendar! 




O The completed ad hoc end-user query. . . © . . .and the results! © Plus, customizable user interface! 



Ask and you shall receive. 

Ad hoc querying at your service. 

Now you can quickly and easily include ad hoc query functionality in your applications 
and make it directly available to end-users! ComponentOne Query is an ActiveX* 
control that collects end-user input and generates an SQL query or a Filter condition at 
run time — no more preparing all imaginable queries in advance at design time! 
Features include: Powerful query engine; Database structure import; Customizable user 
interface (via templates or programmatically); Custom data editors; Query generation control; 
Lookup lists; Multi-table views; Calculated fields; Join relationships and join groups; and more! 

Trust the performance, support, and value you can only get from ComponentOne tools. Download your eval copy today! 




TAKE ADVANTAGE OF OUR FABULOUS LIMITED TIME OFFERS: 

Full Version $399. s 



Premium Support with Subscription.. 



$299. s 



Component^ 



www.componentone.com 

East Coast Office: 1 .800.858.2739 or 1 .41 2.681 .4343 • West Coast Office: 1 .888.228.4839 or 1 .51 0.496.3240 
ComponentOne'" LLC • 4516 Henry Street • Pittsburgh, PA 15213 • USA 

© 2001 ComponentOne LLC All rights reserved All product names are owned by their respective holders. 
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Pointers Add Power and Safety 

Bid farewell to CopyMemory and learn how VB.NET makes 
direct memory manipulation a breeze, 
by Robert Teixeira 



VisualK 




Enhance Performance With ADO 
Connection Objects 

Encapsulating an ADO connection inside a COM 
object lets your application perform better and scale 
more easily. Here's how to use ADO Connection 
objects in COM and MTS. 

by Dimitrios Tsonis 



Client/server application 




N-tier application 
< I >. 

Business Business Business 
object 1 object 2 object n 
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Clear Common C# Hurdles 

Learn how to avoid some of the most common gotchas 
when working with C# from two developers who have 
been using the language for real development for more 
than a year and a half, 
by Don Preuninger and Joe Dour 



Case 1 : 



Program Rets 



Object / 



Object B 



Object C 



Case 2: 



Object A 



Object B 





C# Explorer 

Manage C# Objects 

Managing objects takes more than 
conserving memory. Take better 
advantage of the .NET garbage 
collector for efficient object 
management and increased 
performance. 

by Bill Wagner 

64 

Web Services 

Develop Interface-Based .NET Web Services 

Separating interface from implementation isn't just for 
traditional component-oriented apps — its benefits apply 
to Web Services too. Learn how to develop and 
consume interface-based Web Services in VS.NET. 
by Juval Lov 
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Content Management integrated with Defect and Change Tracking integrated with Requirements 
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When you're facing software 
development deadlines, you want a 
championship team supporting you. Talk about a 
winning combination. Rational" PurifyPlus brings together the 
best development tools for Visual Studio — Rational Purify-, Rational 
Quantify', and Rational PureCoverage* — to help you develop faster, more 
reliable code. PurifyPlus combines the power to automatically pinpoint 
hard-to-find bugs, highlight performance bottlenecks and identify untested code, in a 
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seamlessly teams up with other Rational tools to provide the industry's only complete 
software development lifecycle solution. Visit www.rational.com/offer/allstar3 to get the free 
whitepaper, Develop Fast, Reliable Code with Rational PurifyPlus. 
While you're there, get a free 15 day evaluation copy (downloadable R9tl^7n3l 
on CD) and let the PurifyPlus all-star team start workine for vou todav! the e-deveiooment comoarw 
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Getting Started 

Build a Project 
Documenter Utility 

This ready-made project-documenting 

utility creates formatted rich text files 

from any VB6 project. It uses a variety of 

file-parsing techniques, collections, and 

classes to gather and format project 

information. 

by Stan Schultes 




74 

Best Practices 

Don't Overuse Inheritance 

, Understanding animal 

classification can help you 
get a handle on 
inheritance, when to use 
it, and when other 
alternatives work better, 
by Bill Wagner 



Chordata 

I 



Mammals 
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Desktop 
Developer 

Whip Forms Into Shape 

New in VB.NET, runtime event handlers 
and property extenders give you consistent 
event behavior. 

by Kathleen Dollard 

84 

Q&A 

Cure Your Dates of Culture Shock 

Our experts show you how to format dates 
for different regions, use a stack trace to 
track down bugs, dynamically create ASP 
.NET server controls that use templates, and 
strip the time off of a date in SQL Server, 
by Jonathan Goodyear 
and Robert Teixeira 

90 

ASP .NET 

Easy E-Mail— It's About Time 

Sending e-mail with ASP .NET is so 
simplistic, it's almost embarrassing, 
by A. Russell Jones 

94 

Database Design 

Save Application Preferences 

Using classes to save user preferences to 
your database can work better than using 
the Registry. You get scalability and 
centralization . . . and you'll make your 
users happy. 

by Dianne Siebold 



98 

Black Belt 

Develop an ATL Web Service 

C# has been praised for many things, 
including the ability to create Web 
Services. But you can also create them in 
VC++.NET and ATL Server, 
by Bill Wagner 




■ Pi Visual C> Projects 
] SI' S Visual C++ Projects 
i -£ij .NET Projects 



£j Utility Projects 

■ fil Setup and Deployment Projects 
I El Cj Other Projects 

■ £i Visual Studio Solutions 

Create an ATL Server Web Service Proiei 

Name: ; 



ATL Project 



ATL Server 
Project 



Extended 
Stored ,., 



MFC Active! 
Control 



I CensusServer 



Location; | C:\vcdj 

Project will be created at C:\vcdj\CensusSeryer. 
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FREE Cata 



100+ pages of products 
and information 
for developers! 

Get a FREE subscription 
to our catalog by calling 
800-445-7899 
or subscribe at 
' programmersparadise.com , 



Paradise Picks 



Mew 
Version!} 



Mozquito FML for HomeSite 

by Mozquito Technologies 

Adding the interactive dimension 

Mozquito FML for HomeSite brings the strength 
and agility of XHTML-FML to Allaire's easy-to-use 
editor HomeSite. Mozquito Technologies trans- 
formation engine, Mozquito Matrix, translates the 
files into a format all major browsers can display. 
Benefits: 

• Includes 20 new XHTML-FML tags 

• Checks your XHTML documents for 
validity and well-formedness 

• Enables FML document preview in your 
favorite browsers 

• Is a simple-to-use environment 

• Contains tags for performing client-side 
calculation and input validation 

• Lets you create multiple pages in a 
single document 

• Create online forms, surveys, quizzes 
and more with just a few tags. 



Paradise # 
M3A011B-GI 



99 



NASDAQ: PROG 



visit us at programmersparadise.com 
or call 800-445-7899 








Desaware 





Paradise # 
D39 0421 -Gl 
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by Desaware 

SpyWorks extends the limits of Visual 
Basic by allowing you to do almost 
anything in VB that you can do in other 
languages such as C++. Version 6.3 
includes .NET support for keyboard 
hooks, window hooks and subclassing 
(including cross-task subclassing). 
Examples in both Visual Basic.NET 
and C#. Plus three free 



$ 374. 



TestTrack" 

by Seapine Software™ 

TestTrack Pro and Workgroup are the most 
powerful defect tracking solutions for Web, 
Windows, Macintosh, Linux, and Solaris. 
TestTrack Pro 4 delivers a robust solution 
by providing source control integration; 
data field customization; XML and ODBC support; customer and 
user test configurations; e-mail notification; e-mail bug importing; 
duplicate defect handling; release note generation; and unlimited 
customer care. TestTrack Workgroup 2.0 delivers a rich feature set 




for smaller teams. 




2.0 Workgroup Ed. 
Paradise # 
S96 0140-GI 

'173. 99 



4 Pro Ed. 
Paradise # 
S96 0170-GI 

J 210." 



Intel® Software Performance Tools 

by Intel 

Build Faster Applications, with 
Help Straight from the Experts 
Who Know Processors Best. 

• VTune'" Performance Analyzer non- 
intrusive sampling and call graph profiling 
offer multiple ways to understand 
code performance. 
Call for pricing on compilers. • Intel® C++ Compiler* designed from the 
VTune Performance ground up to take full advantage of Intel's 
Analyzer latest P racessors ' 

Paradise # * ' ntel ' 5 Fortran Compiler* delivers outstand- 
123 0153-GI ' ng application performance with advanced 
„■ features like Profile-Guided Optimization. 

$ 517." 





Server 
Paradise # 
E14 0176-GI 

$ 228. M 

Workstation 
Paradise # 
E14 0170-GI 

s 48." 



Diskeeper 

Automatic disk defragments for Windows fto/Me/NT/2000 

by Executive Software 

NSTL proven to increase system 

performance up to 200%. 

Built to automatically eliminate file fragmenta- 
tion with only a minimum use of system 
resources, Diskeeper represents better 
technology and better economics than any 
other solution available. "Set It and Forget It'" 
functionality gives you totally transparent 
online operation and a lightning fast, Microsoft 
recommended boot-time defrag for MFT and 
Paging Files. Diskeeper provides the fastest 
and most thorough defragmentation possible! 
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FarPoint's Spread 
3.5-New Version! 

by FarPoint Technologies 

Use FarPoint's Spread 3.5 to easily 
incorporate high-level spreadsheet 
and advanced grid features into 
your applications. You get unmatched flexibility at the cell level for 
maximum control over the display and entry of your data, plenty 
of events to respond to user changes and an impressive feature 
list for everything in between, including: import/export capabilities; 

enhanced printing; 1 2 cell types, formulas; 
Paradise # and an improved Spread Designer. 

^ FARP&NT 



J 331. 
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$429.99 



LEADTOOLS Imaging 

by LEAD Technologies, Inc. 

LEAD'S award-winning imaging 
technology is chosen by Microsoft, 
Hewlett Packard, Intel, Boeing, Xerox, 
and thousands of other companies for 
use in their high-volume applications 
and internal systems. LEADTOOLS gives 
developers the most flexible and powerful 
imaging technology available: forms; 
recognition; PDF; EPS + postscript 
support; import/export; compression; 
image processing; color conversion; 
display/special effects; Internet/intranet; 
annotations; medical imaging; OCR; 
barcode recognition; and much more! 




TX Text Control 9.0 

by The Imaging Source 
TX Text Control Does it All. 

A powerful programming component which 
allows developers to easily add into their 
application sophisticated text formatting 
and display capabilities typically seen only 
in large word processing programs. 

Download a 
demo today. 

programmersparadise.com 

Professional Ed. 
Paradise # 

T79 0134-GI TEXT CONTROL 




NuMega DriverStudio 

by Compuware NuMega 
Accelerate Device Driver 
Development 

NuMega DriverStudio brings automation 
to the difficult work of developing device 
drivers. It accelerates device driver 
development while improving testing and 
reliability. With its system-wide visibility you 
can easily find and fix Windows driver 
problems on the developer desktop, in the 



Paradise # 
N19 0M33-GI 

2,499." 



Call 800-445-7899 or visit programmersparadise.com 



personal service: 

Guaranteed Best Prices! 





10-24 Users 
Paradise # 
S3R 0142-GI 
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PR-Tracker" 

by Softwise Company 
Bug Tracking... doesn't 
have to be expensive! 

Integrate bug tracking over the Internet 
and a local area network in one database 
with the same easy-to-use interface. 

PR-Tracker's simple yet powerful 
interface requires no training and 
enables you to configure a project in 
about 15 minutes. Features include: 
customizable data entry, workflow, 
views and queries; one click queries; 
attachments; and email notification. 

* Price per user. 




Paradise # 
T34 0170-GI 

$ 463." 



DevTrack 

by TechExcel 

Powerful Defect Tracking 

DevTrack is the premier defect- and 
project-tracking tool for software 
development teams, helping to ensure that 
development projects finish on time and on 
budget. DevTrack comprehensively tracks 
and manages all defects, change/feature 
requests, and all other development issues. 
DevTrack also provides powerful workflow 
and process automation features, robust 
searching and reporting, and comprehensive 
point-and-click customization. Intuitive and 
powerful, DevTrack provides a scalable out- 
of-the-box solution, at a great value. 
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Sybase EAServer 4.0 

by Sybase 

Using leading J2EE 1 .3 technology, 
Sybase EAServer 4.0 is the high perfor- 
mance, scalable e-Business engine 
that can give you the competitive 
edge to succeed in today's e-Business 
environment. Sybase EAServer is the 
premier choice for application develop- 
ment because of its reliable, dependable, 
and open architecture. This engineering 
design enables Sybase EAServer to 
adapt to existing IT architectures to 
support scalable Web applications. 

a Sybase 

Information Anywhere. 
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B30 0731 -Gl 

$ 287. 9! 



OLETools 

by Becubed 

Build professional front-end applications 
with this collection of components. 
OLETools is a complete set of 60 32-bit 
ActiveX components including; a Tab 
control — for tabbed interfaces; a Tree 
control — for displaying hierarchical data; 
multi-column List and Combo Boxes; and 
various masked input controls for imple- 
menting advanced data verification. Also, 
includes a 3D calendar, and multimedia 
components for playing back AVI, and 
WAV files from within your application. 
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RoboHelp® Enterprise 

Discover How People are Using 
Your Application and Help System 

The newest Help authoring tool in the 
RoboHelp family provides; 

• All the Help authoring benefits of 
RoboHelp Office, plus... 

• Integrated end user feedback reports 
to improve the effectiveness of your 
application and its Help system 

• Natural language search to make 
searching easier 

• Project merging to streamline team 
development. » 

'Limited time pricing. !„„„„„. 
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VSVIEW® 7.0 Reporting Edition 




Paradise # 
C18 0350-GI 

$ 476. 9£ 



by ComponentOne 

ComponentOne VSVIEW Reporting 
Edition adds powerful, flexible 
database reporting to one of our 
most popular ActiveX" controls, 
VSVIEW Classic Edition. Now you 
can quickly and easily create 
Microsoft® Access-style database 
reports for your Visual Basic, VC++, 
and C++Builder applications, plus 
preview, print, and export those 
reports on your computer or over 
the Web. 



New . 
| Version! < 
.3.5 



Paradise # 
K21 0115-GI 

$ 148." 



Visual Build 

by Kinook Software 
3 Automate Software Builds 
Visual Build empowers developers to 
save time and money by creating an 
automated, repeatable process for 
building software. It is a powerful 
but affordable solution that will 
automate the build process without a 
huge commitment of time, and it works 
with the tools you're using today. 



programmereparadise.com 




Paradise # 
V55 011M-GI 

$ 325." 



VMware Workstation 

VMware Workstation increases the pro- 
ductivity of developers and other technical 
professionals by enabling them to run 
multiple operating systems in secure, 
transportable, high-performance virtual 
computers on physical computers. As a 
result, our customers spend more time 
delivering tangible value to their businesses 
and less time installing operating 
systems, rebooting or reconfiguring 
hardware. VMware Workstation supports 
standard operating systems such as 
Microsoft Windows NT, Windows 2000, 
Windows XP and Linux. 



GUARANTEED BEST PRICES* 

Should you see one of these products listed at 
a lower price in another ad in this magazine, 
CALL US! We'll beat the price, and still offer 
our same quality service and support! 
"Terms of the offer: 

• Offer good through October 31 , 2001 

• Applicable to pricing on current 
versions of software listed m 

• October issue prices only M 

• Offer does not apply towards ~ 
obvious errors in competitors' ads 

• Subject to same terms and conditions 
Prices subject to change. 
Not responsible for typographical errors. 




programmersparadise.com 

Download a 
demo today. 



Visual SlickEdit® v6.0 

by MicroEdge, Inc. 

Source code analysis, side-by-side 
file comparison, extensive language support, 
easy to implement and configurable to your 
coding styles. New Java capabilities including 
Java Tool Integration for setting compile, 
execute, debug, javadoc and jar options. 



Paradise # 
M39 0151-GI 
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TeeChart 
Pro ActiveX 
Version 5 

by Steema Software 

The hottest in COM Charting for Windows and 
the Web! Extensive example code for ASP/IIS, 
Visual Studio, Office and more. Multiple export 
formats, Multiple axes, Multiple Chart types in 
2D, 3D and OpenGL. Custom Canvas, Grid, 
Toolbar, built-in ADO and .NET support and 
many specialist financial functions including 
MACD, ADX and Stochastic. 

Download a 

demo today. |£5»I^Kfi£_ 

programmersparadise.com 
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In Canada — call 1 -888-423-2700 (www.pparadise.on.ca) 



Imagine what you can create 
with the right components. 
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Solutions::PI M 
Professional 
Seventeen personal information 
management components 
designed to work together. 
Multi-column day view, week view, 
calendars, alarms, date and time 
edit control — all use common 
properties and events for seamless 
integration into any application. 



Calendar Tools 
Five fast, easy to use drop-in calendar 
components including monthly and 
yearly calendars, drop date edit control, 
scrolling calendar and more. Calendar 
Tools is an affordable, functional 
component solution to meet your 
design needs. 
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Solutions: Schedule 
Schedule up to 32,000 
entities at a time and present 
the schedule in increments 
of hours, days or weeks. 
Schedule multiple lines 
for each entity with a wide 
variety of time-bar styles. 
Drag and drop time-bars 
within the schedule. 
The ideal solution for 
employee and resource 
scheduling. 



DB? P ut together 



Technologies Inc. 

Download a free trial version: www.dbi-tech.com 
or call toll free: 1-800-670-8045. " 




Feedback Shapes Content 

Letters, we get letters. We get stacks and stacks of letters. — "The CBS Mailbag Song" 



It's been a busy month for e-mail and newsgroup postings — 
some positive, some negative, a lot wait-and-see. Of course, 
that wasn't unexpected in light of the magazine's recent 
name change. 

The reaction to the name change has largely mirrored the re- 
action of developers to Visual Studio .NET. Those who think 
Microsoft is moving in the right direction with .NET and are ex- 
cited about the capabilities of that tool have generally welcomed 
the changes to the magazine. Those who think Microsoft has 
made a misstep with VS.NET generally feel the magazine is exac- 
erbating Microsoft's misstep with one of its own. 

I thought I'd share some of this feedback, both to invite more 
and to provide a window into what kinds of changes your fellow 
readers are requesting. I'm also hoping others will use this as an 
opportunity to tell us what kind of magazine they want to see. 
I've chosen a handful of posts from the Talk to the Editors fo- 
rum — posts that are representative of the range of opinions we've 
received on the subject. 

The first e-mail comes from Michael Welch, who responded 
positively to the change: "I think the change is great. One maga- 
zine that covers many of the topics I'm interested in sounds 
great. I don't want five different magazines covering VB, C#, 
SQL, XML, ADO, the .NET Framework, and so on. Having 
one magazine that not only addresses several technologies, but 
some of the best ways to integrate them, sounds fantastic. Truth- 
fully, I don't see how effective it would be to keep them all sepa- 
rate for much longer." 

Larry Linson weighed in at the other end of the spectrum: "I 
tolerated the 'other subjects' introduced into Visual Basic Pro- 
grammer's Journal after it apparently decided that 'enterprise so- 
lutions' were the only thing that mattered and everything else was 
just Getting Started or '101' — beginner stuff. I tolerated that be- 
cause there was still enough, barely, of the level of VB that I use 
that would be helpful to me. Further diluting the content with 
everything VS, especially with an emphasis on .NET (which, 
AFAIK, is only in beta still), cannot help but reduce the coverage 
of interest to me below the level warranting a subscription." 

Dan Fergus took a more wait-and-see approach. Responding 
to a poster who requested we expand the number of pages in 
Visual Studio Magazine, Dan wrote, "I don't think they are 




Patrick Meader 

Editor in Chief 



What do you want to read 
about? Tell me at ednote® 
fawcette.com, or the mag- 
azine's editors at vsmedit® 



fawcette.com. 



going to triple the page count. 
If some of the articles are Stu- 
dio or namespace related, they 
can cover both VB and C# pro- 
grammers and still be useful. 
Maybe one-third VB, one-third 
C#, and one-third Visual Stu- 
dio topics. I could live with 
that! I'll have to wait and see 
how it falls out before I call 
Patrick and yell at him!" 

The prospect of being yelled 
at notwithstanding, I appreciate 
the feedback offered so far. I wish 
everyone felt as Michael Welch 
does, but I would settle for every- 
one to feel as Dan Fergus does — 
to look at the new magazine care- 
fully, then let us know what you 

like and don't like. For those who feel as Larry Linson does, let 
us know which kinds of articles you want to read about in the 
magazine — it's the surest way to find them and the mix you want 
in the future. I'd also like to reiterate that over time, we'll adjust 
the mix so it's representative of what you use Visual Studio for — 
in other words, your feedback is important. 

The hardest part of this job is figuring out what readers want. 
Readers who write in and tell you what they want to read do the 
hard part for you. In such cases, I occasionally follow the advice 
of filmmaker Jean-Luc Godard, who once said the best way to 
critique a movie is to make another movie. In other words, it can 
be an opportunity to invite a critic to write the article he or she 
wants to read. 

Of course, you don't have to write an article if you want to 
see a particular subject appear in the magazine. Instead, you can 
visit our research site at www.ftpresearch.com/vsmag, which 
we'll update monthly as each issue ships. This month, one ran- 
dom respondent will win a Palm V. If you don't like to fill out 
surveys but want to share your thoughts, drop me an e-mail at 
ednote@fawcette.com or e-mail VSM's editors directly at 
vsmedit@fawcette.com. vsm 
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Quick. Easy. 

InstallShield Express. 
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Welcome to the Web Deployment 
Wizard 

The Web Deployment Wizard allows you to build your setup 
for a quick Web deployment. 



Click Next to proceed or Cancel to exit. 



Industry-Standard Installations out of the Box in Minutes. 



You need quick installation development. And that 
means easy-to-use. But you won't sacrifice quality to 
get it. No sweat. Your answer is InstallShield Express. 

InstallShield Express is the easiest and most 
economical solution for quickly developing 
straightforward setups. An intuitive checklist guides 
development. You just point and click through one 
section, check it off, and move on to the next. In just 
six quick steps, you complete everything necessary 
to build your installation. 

Remember: a robust application doesn't necessarily 
mean a complex setup. If you need to copy files, 
make registry edits, install third-party run-time 
executables, or even deploy on the Web, InstallShield 



Express can have you covered in no time, getting 
software to your users faster— even beating your 
competition. 

And now InstallShield Express features 
One-Click Install™ Web deployment technology. 
Your users get one seamless experience right through 
download and installation, skipping "save as" dialogs 
and avoiding endless file searching. And you get to 
digitally sign and password-prated your setups. 

Plus One-Click Install features let users avoid 
downloading several setup components 
if they already exist on their PCs— speeding things 
even more. Your customers will use your software 
sooner, have fewer hassles, and develop an even 



better opinion of your technology. Speedy 
development. And speedy Web delivery. All with 
InstallShield Express. 

So find out more. An evaluation copy of InstallShield 
Express is available from our Web site. But with such 
value available at so tempting a price, why not order 
today? Wth our 30-day money-back guarantee, you can 
get your hands on the full product risk-free and right 
away. And of course the award-winning InstallShield 
support team is available for help on any challenge. 

So there you have it. Ease of use. The security of the 
industry standard. And most importantly, the speed you 
crave. So rush to www.installshield.com and find out 
more right now! 
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Bottom line: it's an InstallShield setup. So everyone knows it works and works well. Here's a few of the features that make it 
happen for InstallShield Express. 



• Enhanced Checklist Design Environment 

• Visual Basic Project Scanner 

• Static and Dynamic File Dependency Scanners 

• VBScript, DLL, and EXE Custom Actions 

• One-Click Install™ Web Deployment 

• 14 World-Wide Languages 



• Advanced Compression Option 

• Nearly 50 Third-Party Technologies 

• Upgrade Authoring 

• Dialog Text Editor 

• Windows XP Support 

• Upgrade to InstallShield Developer 
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© 2001 InstallShield Software Corporation. All rights reserved. 
InstallShield is a registered trademark and service mark of 
InstallShield Software Corporation. All other trademarks are 
the property of their respective owners. 
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Pop Quiz 



You're a developer. Therefore, you have a nasally voice, a 
pocket protector, a complete inability to relate with 
people, an almost supernatural gift for breaking through 
security measures (coupled, by the way, with a disregard for oth- 
ers' privacy), and an intense love of math. 

What? That's all (or at least mostly) wrong? Of course it is. 
I'm not exactly sure where the programmer-as-hopeless-geek- 
outcast stereotype came from {Revenge of the Nerds had a lot to 
do with it, is my guess), but I do have a hunch that — like other 
professionals — we share a number of preferences and experiences 
that give us a certain general character. That character just hap- 
pens to be a lot different than what most people think. 

So, here are some questions you can ask yourself, then ask 
other developers you know. See if you fit the same mold. E-mail 
me (realitycheck@fawcette.com) with your answers and conclu- 
sions. As an incentive, I'll send a PlayStation 2 — I haven't been 
able to get my hands on an Xbox yet — to someone at random. 
I'm interested to see how we're the same . . . and different. 

How did you get started? What was the first program (apart 
from "Hello World") you ever wrote, approximately how many 
lines of code did it require, and what language did you use? Bo- 
nus: Do you remember the first time you sat at a desktop com- 
puter? What computer was it, and when? Secret Bonus: Did you 
ever use punchcards? If so, how did you stay sane? 

Why are you here? Do you remember making a conscious 
decision to be a developer, or did you just sort of slide into the 
role? If the former, describe what made you want to be a pro- 
grammer. If the latter, explain the (probably bizarre) set of cir- 
cumstances leading you to where you are today. 

How important is college? Do you have a formal computer- 
science-related degree? If not, do you envy those who do? If you 
do, do you feel your education has made you a better program- 
mer? Bonus: Is there a point of diminishing returns in college- 
level programming instruction? For example, does having a doc- 
torate in computer science mean you're a guru, or does it mean 
you've been out of the trenches too long? 

What do you like? Which part of the development process 
do you like best? Designing the program? Writing new code? 
Troubleshooting? Streamlining existing apps? What do you like 
about it? Bonus: Which part do you hate most? 

How much does money matter? Are you programming 
more because you love to program or because there's good 
money in it? Would you still be a programmer if it paid, say, 
about the same as being an elementary school teacher? 




Elden Nelson 

Editor 

How are you the same 
as — and different than— 
other developers? Write 
to me at realitycheck® 
fawcette.com. 



How do you explain your- 
self? You're talking with some- 
body who clearly doesn't have the 
foggiest notion of what a pro- 
gram is, much less what a pro- 
grammer does. This person wants 
to know what you do for a living. 
Do you get extremely vague 
("Oh, I work with computers 
..."), or do you settle in and try 
to make him or her understand? 
Bonus: Recount, in detail, how 
you made (or failed to make) this 
person understand. 

Do you like math? Everyone 
thinks that because you're a pro- 
grammer, you must be a math 
wiz. Are you? 

What would you have done 
for a living 200 years ago? The first floppy disk won't be on 
store shelves 'til looooong after you're dead. What do you do 
instead? 

Have you ever hacked? Have you ever used your program- 
ming skills to do something you shouldn't have? If so, do you 
now regret it? If not, are you sometimes tempted? Bonus: One of 
the most common things you see computer programmers do in 
movies is break codes. Could you — right this instant, without 
doing a bunch of research — do this, if you wanted to? 

What's your proudest programming moment? At some 
point, you wrote a program — or part of a program — that proves 
you're a genius. Did anybody else recognize your Einstein mo- 
ment? Bonus: Did you go out of your way to make sure some- 
body recognized your development epiphany? 

What's your biggest moment of programming shame? At 
some point, you (probably) wrote something you now realize is 
complete trash. Did you realize it was garbage at the time? Did 
you fess up? Does it still haunt you at night? 

What's the best trade show swag you've ever received? 
Surely you've admitted to yourself that one of the reasons you go 
to trade shows is to pick up the free stuff. What's the coolest free 
thing you've ever gotten? 

What would you say to set the record straight? A major 
network calls you and says they've reserved two minutes of air- 
time for you to explain to the world what developers are really 
like. What do you say? 
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Letters to Visual Studio Magazine are wel- 
come. Letters must include your name, 
address, and daytime phone numberto be 
considered for publication. Letters might 
be edited for form, fit, and style. Please 
send them to Letters to the Editor, c/o 
Visual Studio Magazine, 209 Hamilton Av- 
enue, Palo Alto, CA 94301-2500; fax them 
to 650-853-0230; or e-mail them to 
vsmedit@fawcette.com. 



Newer * Better 

In regards to Reality Check, "Are You a 
Techno-Retro-Grouch?" by Elden Nelson 
[Visual Basic Programmer's Journal August 
2001]: The problem, as I see it, is one of 
attitude. I think a lot of programmers be- 
lieve programming is about technology, 
when it's really the other way around — 
technology is about programming. It's a 
way to get certain things done faster and not 
really the end in itself. Libraries and frame- 
works and platforms will never be a substi- 
tute for creativity and perseverance. People 
seem more interested in acquiring a long list 
ofacronyms (XML, JSP, EJB ...) rather than 
acquiringadeep understanding of the means 
of creating algorithms and machine archi- 
tecture. Without knowledge of these two 
things, it's difficult to do much more than 
assemble some configuration of a prefabri- 
cated machine. 

I see a lot of new applications but few 
new concepts. Maybe I am a techno-retro- 
grouch, but to be one at the age of 26 seems 
a sad commentary. It's not that I want to go 
back to hand-crafting 3-D graphics algo- 
rithms in 8088 assembler or that I believe 
you're not a programmer if you don't code 
in C. I'm just a little saddened when I meet 
programmers who cannot appreciate the 
beauty of a game such as Pong. 

Marvin Wilson, New York 

I became tired of the incessant and increas- 
ing "progress" in technology around the 
time Windows debuted. Every few months, 
there's a new operating system and a new 
language version. We learn HTML and out 
comes XML. We learn VB6 and out comes 
VB.NET. We learn Access and they want 
Oracle. We have no time to devote to appli- 
cations due to system software updates. 

I don't see how anyone has the time (or 
ability) to keep up with this nonsense. Re- 
cently, VBPJ had an article on VB.NET and 
its differences from VB6 ["Drill Down on 
VB.NET" by James Foxall, February 2001]. 



Our current code won't work. I sighed when 
I learned about the demise of control arrays 
and considered the redundant code neces- 
sary to replace them. And then, the bomb- 
shell. No native file support! WHAT? I can't 
access a simple flat file? No byte-stream I/O? 
That means I can't use VB.NET. It also 
means I won 't use it. 

I have had enough. I'm getting out. I 
retired last month, and shall use VB6 at 
home until it rots, at which time I shall 
revert to paper and pen. 

Dave Westfall, Southfield, Mich. 

VB Does Graphics, Too 

Thank you so much for the article "Take 
Control of DirectX" by Jonny Anderson 
[Visual Basic Programmer's Journal June 
2001]. In the past, so much of your maga- 
zine was devoted to databases, it really was a 
breath of fresh air to see an article on graph- 
ics. VB is capable of so much more. My hat 
is off to you. 

Robert Martin, Longview, Texas 



Get the Code 

Use these Locator+ codes to download the code for 
this issueof KSM at www.vbpj.com orwww.vcdj.com. 



VS0110 



1 



VS01 10: All the listings and code files for the Octo- 
ber 2001 issue of VSM in one ZIP file 
VS0110RT: "VB.NET: Pointers Add Power and 
Safety": Listing 1 , which shows you how to create a 
read-only view into a text file 
VS0110DT: "Enhance Performance With ADO 
Connection Objects": the code to create the COM 
and MTS implementations of the DLL described in 
the article 

VS0110CE: C# Explorer: Listings 1 through 4 and 
the finished project that creates, displays, and ani- 
mates the Mandelbrot set 

VS01 10WS: Web Services: a basic, non-interface— 
based Web Service; two interface-based Web Ser- 
vices; a test client that uses them all; and Listings 
4 and 5 

VS01I0GS: Getting Started: a complete utility to 
create VB project documentation, as well as Listings 
A, B, and C, which weren't printed due to space 
constraints 

VS0110DT: Desktop Developer: the extender class 
and a test project that demonstrates its use 
VS0110QA: Q&A: C# code for the first two ques- 
tions (Listings A and B), VB.NET and C# ASPX 
files for the dynamically created Repeater control, 
and the SQL script for stripping the time off of a 
date in SQL Server 

VS01 10AN: ASP.NET: code to create a WebForm 
that users fill out to send e-mail from your Web site 
VS0110DD: Database Design: a sample application 
demonstrating the classes for saving and retrieving 
user preference. 1 ; 

VS0110BB: Black Belt: a Web Service built using 
C++ and ATL Server, that same Web Service built 
using C#, and a C# client that uses the Web Service 
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The .NET Learning Curve 

Dan Appleman, leading author on VB 

The biggest challenge .NET poses to Windows developers today is not deployment - it's 
education The .NET Framework is so huge and so different, that you'll need to invest significant 
time studying and experimenting with .NET before you start deploying real applications. How 
does one go about learning .NET? Expensive courses and conferences? Books? Articles? 
Regardless, it is essential to first leam the core concepts of .NET. That is the foundation on w inch 
you can base further learning, and that's the focus of my new book "Moving to VB.NET: 
Strategies, Concepts and Code". You can read the introduction and sample text at 
www.desaware.com. There you'll also read about Spy Works 6.3 with .NET support, 
VersionStamper's support for .NET applications that use COM components, and new products 
designed specifically for .NET Dan 




NT Service Toolkit 
Full featured services with VB6! 

Visual Basic programmers have long searched 
for a good way to create NT Services using 
Visual Basic. Yet every solution they found had 
serious limitations and compromises - until now. 
Desaware's NT Service Toolkit provides all the 
power of a C++ service from VB - but the 
services are far easier to create and debug! 

• Debug your service using the VB environment - while it is 
running as a service! 

• Automatic background threads for waiting on NT 
synchronization objects. 

• Access and control services through COM or DCOM 

• Expose client objects via COM or DCOM. 

• Client objects run on a thread pool for scalability. 

• Create background threads for asynchronous operations. 

• Create control panel applets to manage your services. 

• All service notifications (including those new to Win 2000). 

• Simulator allows testing without installing as a service. 

• Impersonation allows acting on behalf of clients. 

• Access to all service configuration parameters. 

Escape DLL Hell! 

VersionStamper helps eliminate incompatibility 
problems that can occur when distributing 
component based applications - including .NET 
applications that use COM components Your 
application can analyze a client system using an 
embedded dependency list or data from your 
Web or FTP site. Problems can be resolved by 
notifying the user, reporting via Email, or automatic download 
of the correct components from your Web or FTP site. 

i New! Event Log Toolkit 

I Create custom event sources with this easy to 
I use toolkit. Eliminates the problem with VB6 in 
I which all events are logged as coming from 
I VBRuntime. Event sources are easy to 
I distribute, self-installing, and support multiple 
I languages. Included code demonstrates 
advanced event reporting API calls. 



Data Storage for VB, VBA 
and Internet Applications 

StorageTools allows you to create complex 
documents, each of which can be subdivided 
into multiple named blocks of data. StorageTools 
actually gives you more data storage flexibility 
than most databases, without the overhead! 






SpyWorks® 6.3 - The ultimate low 
level toolkit, now compatible with 
VB.NET and C#for VS.NET Beta 2 

Advanced Subclassing and Hooks - In-and 
cross process subclassing for VB6 and .NET! 
Use Windows Hooks to intercept messages 
and keys for a window, process or the entire 
system. Create Background threads for your 
VB6 DLL COM objects. Create true Function Exports from 
your VB6 DLLs. Handle Internet/Intranet communications with 
our Winsock Component - with VB source. Create Control 
Panel Applets. Implement or call ANY interface - No type 
library. And much more.... 



Books 




Moving to VB.Net: Strategies, 
Concepts and Code 

VB.Net is not Visual Basic. Porting is stupid. COM is 
"dead". These are just a few of the things you'll learn 
as Dan takes you on a journey unlike any other into 
the world of VB.Net. Covers adoption strategies, 
unlearning VB6 concepts that are fatal in VB.Net, 
and analysis of language changes that goes beyond 
the documentation, apress, isbn 1-893115-97-6 

Visual Basic.NET or C# - Which to Choose? -A 

new PDF based e-book comparing VB.NET and C# 
available now at www.desaware.comA/BorCsharp.htm. 

How Computer Programming Works -The ideal 
book for beginning programmers. Teaches the 
fundamentals of programming using illustrations and 
* real world analogies. APRESS, ISBN 1-893115-23-2 

Also available 

Dan Appleman's Visual Basic Programmer's Guide 
to the Win32 API - The core Windows Software 
Development Kit rewritten for VB programmers. Dan 
Appleman's Win32 API Puzzle Book and Tutorial for 
VB Programmers teaches you to call any API function 
from VB5 & 6. Developing COM/ActiveX Components 
with Visual Basic 6.0. The essentials of COM and 
component development for VB. 

For more information, please visit... 

www.desa wa rG.com 

Desaware Inc. 

1100 E. Hamilton Ave., Suite 4 
Campbell, CA 95008 
tel: (408) 377-4770 fax: (408) 371-3530 
email: support@desaware.com 




Herd about COW? 

Cache bjectS for the Web Introducing the fastest way to build sophisticated 
database applications for the Web. Featuring dynamic server pages, and simple-to-use 
yet powerful object technology. With the world's fastest and most scalable Web 
database, Cache, already built in. Compatible with other popular databases and leading 
Web design tools. 

InterSystems f 



£ CACHE 



Download a fully-functional COW, or request it on CD, free at: www.CACHE-COW.com 

Or call 1-800-753-2571 

© 2001 InterSystems Corporation. All rights reserved. InterSystems Cache is a registered trademark of InterSystems Corporation. 



A Web Site Dream Team 



The technologies needed to create increasingly sophisticated 
Web applications are growing more complex. Gone are the days 
when building a Web site with Notepad was feasible. If you need to 
put together a site — in Internet time — you need the right tools. 

I've long relied on Microsoft's FrontPage and Visual InterDev, 
but Macromedia's Dreamweaver 4 Fireworks 4 Suite (bundling the 
company's two products together and giving it way too long of a 
name) provides some tempting reasons to switch. This is a compre- 
hensive package ofW eb and graphics development tools that has the 
added benefit of extensibility. 

Dreamweaver is a Web site design and development tool that 
includes an HTML editot, support for W3C standards and acces- 
sibility features, support for CSS, and, well, everything you need to 

Dreamweaver 4 Fireworks 4 Studio 

Macromedia 

Web: www.macromedia.com Phone: 415-252-2000 
Price: $399 

Quick Facts: Extensive collection of Web site and application tools, with plenty 
of support for graphics-intensive sites. 

i: Virtually everything is in the box; great documentation and support; many 
eaturesto round out the products. 

i-consuming to learn; lack of good programming database support 
in the UltraDev edition). 




Help is on the Way 

One thing that seems to pervade every type of project, regardless 
of language or the degree of programmer proficiency, is a lack 
of documentation — both written manuals and help files. 

RoboHelp Enterprise is a one-size-fits-all attempt to address 
that situation. After spending some time with it, I've concluded that 
it's a real powerhouse. The Enterprise incarnation is a superset of 
the other target-specific RoboHelp versions. It also adds server-side 
functionality not present in any other version. 

These additional features use eHelp's MindReader server, which 
runs under Internet Information Server (IIS). There are two types of 
MindReader features — a natural-language search engine, which is 
aimed at your end users, and a set of report functions, aimed at the 
administrative and development people working on the project. The 
natural-language feature requires the RoboHelp Enterprise project 
type; it won't work with HTML Help, WinHelp, or any of the other 
targeted platforms that RoboHelp supports. This isn't an issue for an 



RoboHelp Enterprise 
eHelp Corp. 

Web: www.ehelp.com Phone: 800-358-9370 
Price: 81,798 

Quick Facts: An all-encompassing help development system. 

Pros: Powerful; covers a wide array of target platforms. 

Cons: Natural language engine requires IIS; can't be deployed to standalone apps. 



Graphics to Die For. Fireworks 4, which comprises half the suite, 
provides a rich set of bitmap and vector tools that let you create, edit, and 
animate your Web graphics. Macromedia is positioning Fireworks 4 as 
a direct competitor to Adobe Photoshop 6 for professional Web design. 

build rich Web sites and applications. This latest version adds a slew 
of new features, including an integrated text editor with color-coded 
HTML and scripting code, a JavaScript debugger, and an integrated 
O'Reilly code reference for information about tags and objects. One 
cool new feature is the Asset Management Tool, which lets you track 
all site media — including site images, colors, and external URLs — 
in a central location. 

The other product in the suite is Fireworks 4, which you use to 
design and optimize Web graphics for easy integration into your 
site. It also sports many new features, such as a popup menu creator 
to implement cool site navigation without writing all the messy 
client-side code; a Layers panel, which has expanded thumbnails of 
each layer's objects and advanced masking capabilities; and a Batch 
Processing Wizard for executing multiple processes. Fireworks' 
support for importing and/or exporting graphic elements now 
includes Photoshop, FreeHand 9, EPS, and wireless BMPs. 
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An IDE by Any Other Name. RoboHelp Enterprise's Authoring 
Environment has a similar feel to FrontPage, and the resemblance is 
more than skin-deep — you can use it to develop Web sites, too, 
complete with natural-language search functions. The HTML Help 
Environment handles all the help formats except for legacy WinHelp 
HLP projects; the RoboHelp Classic Environment, included with the 
Enterprise edition, manages these projects. 

organizational intranet or even an Internet application that can access 
your Web server, but it precludes you from adding natural-language 
searches to your standalone, non-networked projects. 

The Enterprise project type maintains a database on the server 
and uses it to generate a variety of live reports. You can see charts 
detailing the access frequency for each page, the number of unan- 
swerable questions posed to the system, the most common ques- 
tions asked, and so forth. This gives you the opportunity to hone 
your help system to address demonstrated needs rather than the 
merely anticipated needs that all help systems aim to meet. 

RoboHelp Enterprise can be overkill for developers who don't 
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tiJ MSDN Subscription Download* 

1 Visual Studio .NET Beta 2\* 

B Visual Studio 6.0 Ent. Ed. 
@ .NET Framework SDK 
S SQL Server 2000 
9 Commerce Server 2000 
g BIzTalk Server 2000 
3 Windows XP 
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Tired of ad fluff? Get essential developer resources with an MSDN" Sub 

Want to get priority access to over 1,000 continuously-updated f 
downloads, DVDs, or CDs with the latest tools, platform, and s 

technologies? Get an MSDN Subscription, and start building yo 
big thing, msdn.microsoft.com/subscriptlons 



A Web Site Dream Team 

Macromedia products are complex and 
state-of-the-art, which usually means the 
learning curve is steep. This suite is no excep- 
tion, but the company is working to make its 
various products easier to learn and use. The 
suite's comprehensive documentation, in- 
structional videos, help files, and extensive 
Web site do help navigate the learning curve, 
but don't expect to crank out a professional 
Web site after your first all-nighter. 

All I found missing in this bundle are 
the features that Dreamweaver UltraDev — 
Dreamweaver 4's big brother — provides, 
such as easy data access and extensive sup- 
port for programming. So big-time Web 
developers will probably want to spend the 
extra $300 and get the UltraDev 4 Fire- 
works 4 Studio bundle. But if you're a 
designer who doesn't write code, this bundle 
is probably more than enough. 

For the first time with a Web site develop- 
ment tool, I feel like I did when I first used 
Microsoft Office — it has many more features 



than I'll ever use, but it's nice to have them 
available as I discover what they do. Sigh. It 
might finally be time to give FrontPage and 
Visual InterDev their pink slips, vsm 



Don Kiely is a senior software technologist 
for Third Sector Technologies in Fairbanks, 
Alaska. He's written several books about VB 
and VC++, and he speaks regularly at VBITS. 
Reach him at donkiely@computer.org. 



Help is on the Way 

need to target enterprise systems but do 
need to develop intensive help systems for 
standalone applications. Although Robo- 
Help Enterprise compiles help systems for 
HTML Help, WinHelp, JavaHelp, Oracle 
Help, and eHelp's browser-oriented 
platform-independent WebHelp format, 
you don't need it to target those formats. 
The RoboHelp Office version, which costs 
roughly half as much as the Enterprise 
version, tackles those formats exactly the 
same way as the Enterprise version. And, 



because the Office version is a superset of 
the HTML Help and Classic versions, you 
can save even more by purchasing one of 
those two systems if you don't need to work 
with WinHelp files and the rest of the 
supported formats. 

There's no way to address the fantastic 
array of development functions that all of 
these packages provide. In addition to creat- 
ing help systems, you can also import and 
translate existing systems and output help 
systems to written manual format to take 
care of your printed documentation needs. 

You can download 1 5-day evaluation cop- 
ies from eHelp's Web site, so you should try 
the systems before committing to a purchase. 
Unless you work in an environment where no 
documentation is mrrequired, I think you'll 
enjoy working with RoboHelp. vswi 



Ron Schwarz lurks in rural Michigan. When 
he's not digging out of the mountain of e-mail 
in his inbox, he maintains his sanity by restor- 
ing classic cameras. He welcomes your com- 
ments at www.clubvb.com. 



Apress 

The Ultimate .NET Resource 





A Programmer s 1 
Introduction toC# 

Second Edition 



ISBN: 1-893115-97-6 $39.95 



ISBN: 1-893115-59-3 $59.95 



ISBN: 1-893115-99-2 $39.95 



ISBN: 1-893115-62-3 $39.95 



Apress, located in Berkeley, CA, is an innovative publishing company devoted to meeting the needs of existing and potential pro- 
gramming professionals. Simply put, the "A" in Apress stands for the "author's press™." Apress' unique author-centric approach to 
publishing grew from conversations between Dan Appleman and Gary Cornell, authors of best-selling, highly regarded computer books. 
In 1 998, they set out to create a publishing company that emphasized quality above all else — a company with books that would be 
considered the best in their market. Dan and Gary's vision has resulted in over 35 titles by many leading software professionals. 

Books for professionals by professionals™ • www.apress.com 

Available at bookstores nationwide or from Springer-Verlag New York, Inc. at 1-800-777-4643; fax 1-212-533-3503. 
Contact us for more information at sales@apress.com. 
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Deliver Spreadsheets 
Over the Web 

ExcelWriter 2.0 is a server-side component for Internet Informa- 
tion Server (IIS) that generates Microsoft Excel spreadsheets 
from a data source. Using Active Server Pages (ASP), you can 
produce text, graphs, and charts that correspond to the BIFF 8 
format used by Excel 97, 2000, and 2002. This capability lets you 
take advantage of Excel's rich formatting and formulas while 
providing the latest statistics from your database. The budget- 
conscious should take note that you don't even need to buy Excel 
to run or view reports — the component works without requiring 
Excel on the Web server, and Microsoft offers a free Excel reader. 
During the easy installation, watch for a privacy issue. The 

ExcelWriter 2.0 

SoftArtisans 

Web: www.softartisans.com Phone: 877-SOFTART 
Price: Server license starts at S799. 

Quick Facts: Component that generates Excel spreadsheets, reports, and 
charts from scripts or databases. 

Pros: Flexible and sophisticated; built for high-powered Web use; good docu- 
mentation and sample code. 

Cons: No supportfor pivottables; sends registration information to SoftArtisans 
without prompting; no fixed price. 



Snuff Out 
Resource Leaks 

Finding bottlenecks and resource leaks in your code is a crucial 
part of testing and deploying robust applications. There are 
many choices out there for tools that can help you with these tasks. 
Most of them are large, complex, and costly. 

But Electric Software's GlowCode is an excellent tool for 
profiling and understanding your code and detecting memory leaks 
at an affordable price. The tool is simple and straightforward to use, 
and I was able to get meaningful, detailed, and easily understandable 
results in minutes the first time I used it. 

Using GlowCode starts with the GlowCode Loader, which 
allows you to choose whether you want to launch your app from the 
loader directly, attach the GlowCode Profiler to a running process, 

GlowCode 3.0 

Electric Software Inc. 
Web: www.glowcode.com 
Price: $295 

Quick Facts: Quick and easy profiling tool that snuffs out resource leaks and 
bottlenecks. 

Pros: Fast; easy to learn and use. 

Cons: Slightly primitive user interface; sparse online documentation. 




Generate Excel Spreadsheets- Without Excel. ExcelWriter 2.0 lets 
your Web server deliver Excel spreadsheets on the fly without requiring 
Microsoft Excel on the server. You can connect to an ADO data source and 
program ExcelWriter's objects using ASP to generate 2-D and 3-D charts. 

license says the product sends your registration data to SoftArtisans 
automatically. Specifically, "HRESULT of registration, Username, 
Computername, Domainname, Time Zone, OS Version, Locale 
Id, Browser Version, Source IP Address and CPU count." 

To give ExcelWriter a spin, I used ASP to read data from an 
Access database and push the results out to Excel as a sorted table. 
Thanks to the example files, producing a simple spreadsheet appli- 
cation takes only a few minutes. Use the familiar ActiveX Data 
Objects (ADO) to connect to the database and execute a SQL query. 
After assigning values to the cells, you define the style of the columns 
using ExcelWriter's CreateStyle method. For example, you can 
format a date using DateStyle. Number = 1 7, or you can set the width 
of a text column using cells. ColumnWidth(i) = 20. 

If you're generating Excel spreadsheets, you probably also want 



GlowCode Finds a Leak. GlowCode detects leaked resources quickly 
and easily, providing detailed information to help track down the cause. 

or link the GlowCode toolset directly into your application. If you 
choose the latter, you get some brief instructions to add the provided 
glowcode.cpp file to your app. But you also need to ensure the 
GlowCode gc2core.dll file is either in your program's folder or in a 
system path folder where you can find it. If you're going to use 
GlowCode with a release version of your program, you also need to 
make sure a program database (PDB) is available. 

Once GlowCode is attached to a running application through 
any of these means, the GlowCode Dashboard arrives to provide 
information on the running program. The Dashboard is an easy-to- 
use tabbed interface with tabs for each of the program's main 
functions: Profiler, Trace, Coverage, and Resources. There's also a 
More tab, which is where you find the basic program functions 
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Deliver Spreadsheets ... 

to display charts. ExcelWriter makes that 
easy, too. In many ways, you are repeating 
the programmatic steps you would take if 
you were working on the spreadsheet within 
Excel. For example, to show a 3-D bar chart, 
you generate the data, put it into cells, select 
ranges, and set the format for the type of 
chart. Anyone who is comfortable in VBA 
will grasp the objects in ExcelWriter easily. 
One disappointment is its lack of support 
for pivot tables. That addition would give it 
a big competitive boost against reporting 
products from Crystal Decisions. 

In my examples, I generated spread- 
sheets on the fly. For static reports, schedule 
a Windows Scripting Host script to write a 
single XLS file to the file system instead of 
streaming new spreadsheets to each user. 

ExcelWriter is fun to use, works well, 
and provides good documentation and ex- 
ample code. For the forward-thinking pur- 
chaser, SoftArtisans' Web site shows the 
product working already in ASP .NET. A 



server license starts at $799 per CPU for the 
light version, but you'll have to contact the 
company on pricing out the full version of 
the software because it is "negotiated on a 
per purchase basis." You can obtain a free 
evaluation download from http://support. 
softartisans.com/evalindex.asp. \ 



Ken Cox is a technical writer and Web appli- 
cations developer in Toronto. A former broad- 
cast journalist, Ken is also a Microsoft MVP. 
Reach Ken at kjopc@hotmail.com. 



Snuff Out Resource Leaks 

normally found in a menu, such as Help, 
options, version info, and so on. 

The Profiler, Trace, and Coverage tabs 
take a consistent approach, consisting of an 
expandable treeview display that lets you 
drill down to the module, file, function, or 
line of code level. There are also additional 
columns in the tab that display the results of 
that tab's purpose. Each tab has buttons to 



start and stop the profiling, clear the display 
and counts, change the current hooks into 
the program, export the displayed results to 
a file or the clipboard, or get options relevant 
to the tab's function. You can hook into 
system or linked DLLs that your program 
uses if you want to see their contribution to 
your code's performance. 

You can use GlowCode as a simple tool 
during ad hoc testing to ensure you get good 
coverage of your code, or as a cross-check of 
test suites to make sure you're getting the 
coverage you think you are. The documen- 
tation is a little sparse and the user interface 
a bit primitive, but because the tool is so 
straightforward and intuitive, you don't need 
a fancy GUI or reams of documentation to 
get useful results in a hurry, vsm 

Brian Noyes is a senior software engineer 
with Digital Access Corp. He's an MCSD 
with nine years of software development, 
project management, and test and evalua- 
tion experience. E-mail him at bnoyes® 
domeworks.com. 
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Focused on the latest Microsoft® Technologies 
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Hosting Platfo 

Windows 2000 Se 
SQL Server 2000 
MS Access 2000 
ASP / XML / WAP 
ASP Components 
Live Statistics 
Active Directory 
HostMechanic™ 



Development Tools 

MS FrontPage 2002 
Visual Studio.NET 




Microsoft* 

FrontPage* 

^=^120021 

The fast, easy way to create 
and manage professional 
Web sites! 

• Generates HTML code. 

• Easily add E-commerce 
functionality to your site. 

• Automatically updated Web 
content (MSNBC, Expedia) 

■ 67 Customizable Themes 
updated for 2002! 



[Microsoft* 

Exchange2000 

Server 

Ideal platfonr) for business 
critical messaging. Powerful 
collaborative features! 

• Keep your company's staff 
up-to-date in real time! 

• Unified management of all 
messaging, collaboration and 
network resources. 

• Greater efficiency and power j 
by unifying information flow. 



Microsoft 

SharePoinf 

Team Services - 



A team Web site solution 
designed to improve the way 
a team manages infomnation! 

• Seamless communication 
and efficient collaboration. 

• Document Libraries 

• Discussion Boards. 

• Customize from a Browser. 

• Customize with Microsoft" 
FrontPage* version 2002. 



Microsoft 



.net 



The Next Generation Internet... 

Our research and development technicians have been working with .NET since its 
inception in preparation of supporting this new and innovative Microsoft® platform! 
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tion to Product Listings Editor, c/o Fawcette 
Technical Publications,209 Hamilton Avenue, 
Palo Alto, CA 94301-2500; fax: 650-853-0230; 
e-mail: vsmedit@fawcette.com. 



Dataphor 

Dataphor is designed to provide responsive 
and thorough data access and manipulation. 
Written in C#, the program consists of a lan- 
guage specification and a server architec- 
ture. Features include unified navigational 
access, an extensible data dictionary, data- 
base-level constraints, and the ability to up- 
date queries. Contact for pricing. 
Softwise 

Phone: 888-324-3988; 801-221-8222 
Web: www.softwisetools.com 

Gen<X> 

Gen<X> is designed to capture code written 
into templates and reuse it from project to 
project. The program combines changing in- 
put variables with static code, using an engine 
to merge at run time, and a syntax to declare 
the variables when making a template. The 
syntax is virtually an exact match to Active 
Server Pages (ASP) and does not require a 
Web server to run. Contact for pricing. 
DevelopMentor 
Phone: 310-214-7800 
Web: www.develop.com 

Interphor 

Interphor is a group of technologies that gen- 
erate user interfaces dynamically using in- 
formation provided by the data dictionary. 
The interfaces are then presented using a 
thin client metaphor. You can tailor complete 
applications to fit the requirements of any 
project. Contact for pricing. 
Softwise 

Phone: 888-324-3988; 801-221-8222 
Web: www.softwisetools.com 

Updates: 

Acceler8DB 4.7 

Acceler8DB is a client/serverdatabase man- 
agement system designed for Windows and 
AS/400 systems. The program allows appli- 
cations to access multiple Acceler8DB and 
DB2/400 databases concurrently and inter- 
changeably. The program stores and pre- 
sents data through physical and logical files. 
You can also store data on standalone PCs or 
on Windows NT/2000 servers accessible by 
TCP/IP. Acceler8DB is equipped with an 
Acceler8DB Manager to facilitate the admin- 
istration of database and print files. Contact 
for pricing. 
ASNA 

Phone: 800-289-2762 
Web: www.asna.com 

AppForge 2.0 

AppForge 2.0 enables Visual Basic developers 
to create applicationsfor Palm OS, Pocket PC, 
and Win32-powered devices using a single 
code base. It also allows PDB libraries to run 
on the Pocket PC, giving cross-platform func- 
tionality. New features in version 2.0 include 



color support, dropdown menus, user-defined 
classes, double-precision floating-point op- 
eration, overlapping control support, larger 
code segments, and currency support for Vi- 
sual Basic 6.0. Contact for pricing. 
AppForge 

Phone: 678-686-9000 
Web: www.appforge.com 

AppForge SDK 2.0 

AppForge SDK 2.0 is a collection of files, 
libraries, and utilities that allow you to use 
Visual C++ to create applications and ActiveX 
controls for Palm OS, Pocket PC, and Win32- 
powered devices using a single code base. 
The ActiveX controls created with the SDK 
are designed to integrate seamlessly with 
AppForge 2.0. The program integrates with 
Visual Studio for Windows, Metrowerks 
CodeWarrior, or PRCTools for Palm OS. Con- 
tact for pricing. 
AppForge 

Phone: 678-686-9000 
Web: www.appforge.com 

CAST Application Mining 
Suite 4.0 

CAST Application Mining Suite 4.0 is a suite 
of tools that generates a graphical roadmap 
of client/server applications and databases, 
showing the structure of a system and the 
interrelationship of its objects. Its drill-down 
views and change-impact analysis are de- 
signed to help you gain control of large, com- 
plex database applications. It supports SQL 
Server and Oracle databases as well as ap- 
plications written in Visual Basic and Pow- 
erBuilder. It also offers limited support for 
3GL code stored as ASCII text, such as Visual 
C++. New features in version 4.0 include a 
new Java Analyzer, support for J2EE- and 
NET-compliant applications, optimized leg- 
ibility of graphical views, and a new HTML 
Report wizard. Contact for pricing. 
CAST 

Phone: 415-296-1300 

Web: www.castsoftware.com 

Chart FX Client Server 

Chart FX Client Server is a COM-based, 32-bit 
charting tool that lets you deploy powerful 
charts in your VB, Visual C++, Delphi, and 
Access applications. The program includes 
an OLE server, server extensions, and Client 
Server wizards. It is recoded completely in C# 
to ensure .NET compatibility. New features 
include increased security, integration with 
Web Services, enhanced XML support, new 
API and Flash generation, use of new GDI 
features, and adoption of the WindowsXP OS 
look and feel. $499. 
Software FX 

Phone: 800-392-4278; 561-999-8888 
Web: www.softwarefx.com 

Chart FX IE 2000 

Chart FX IE 2000 is a charting tool for Internet/ 
intranet developers. It offers the same chart- 
ing engine as Chart FX Client Server; an im- 
age painter; the ability to generate ASP, 
ColdFusion, and client-side code; and Visual 
Interface 6.0 compliance. New features in- 
clude increased security, integration with 



Web Services, enhanced XML support, new 
API and Flash generation, use of new GDI 
features, and adoption of the Windows XP OS 
look and feel. Starts at $1,399. 
Software FX 

Phone: 800-392-4278; 561-999-8888 
Web: www.softwarefx.com 

Database Toolbox 

ASNA Database Toolbox connects ASNA's 
Acceler8DB database to Windows and Web 
applications. The toolbox is a scalable data- 
base management system designed specifi- 
cally for Windows and Active Server Pages 
(ASP) applications, providing directdatabase 
access for the AS/400, Windows NT/2000 
Server, and local PCs. You can use it with 
Visual Basic, Visual C++, and Java. Contact 
for pricing. 
ASNA 

Phone:800-289-2762 
Web: www.asna.com 

DB2 Universal Database 7.2 

DB2 Universal Database 7.2 is a Web-enabled 
relational database management system. It 
is scalable from single processors to sym- 
metric multiprocessors to massively parallel 
clusters. New features in version 7.2 include 
new assist wizards, Sybase and SQL Server 
wrappers, a DB2 Connect Web Starter kit, 
and support for messages, including XML 
documents. Contact for pricing. 
IBM 

Phone: 800-IBM-4Y0U; 914-499-1900 
Web: www.software.ibm.com 

NT Service Toolkit 1.1 

NT Service Toolkit 1.1 is a framework that lets 
you write fully featured NT/2000 services 
while adhering to Visual Basic's program- 
ming and threading rules. The program sup- 
ports all NT service options and controls. It 
supports client requests on independent 
threads for scalability, with available client 
impersonation allowing services to act on 
behalf of clients in their own security context. 
Client requests and service control is pos- 
sible through C0M/C0M+/DC0M. You can 
build monitors, background taskers, agents, 
resource pools, and business objects using 
Visual C++. $499. 
Desaware 
Phone: 408-377-4770 
Web: www.desaware.com 

R:FJ ASE 2000 6.5 

R:BASE 2000 6.5 is a PC-based database man- 
agementsystem based onthe relational model. 
It provides intuitive interfaces, such as 
clickable images, and user-defined functions 
that offer direct control of function specifica- 
tion. The engine allowsfor large, customizable 
data queries; you can use it over a network 
without setting up a network server file. Fea- 
tures in version 6.5 include support for long 
filenames, support for calling DLLs, form flex- 
ibility, the ability to use PAUSE 3 functionality 
and WALKMENUs in a Windows environment, 
and context-sensitive help. Starts at $500. 
R:BASE Technologies 
Phone: 724-733-0053 
Web: www.rbase.com 



Rational Rose 2001a 

Rational Rose 2001a is a graphical compo- 
nent modeling and development tool that fa- 
cilitates software application modeling. The 
program lets you visualize your applications 
graphically using industry-standard UML. It 
supports generation and round-trip engineer- 
ing in C++, Visual Basic, and Java. New fea- 
tures in version 2001a include the ability to 
forward- or reverse-engineer directly to an 
IDE, the ability to search for JDKs automati- 
cally, 20 new design patterns, enhanced J2EE 
support, support for modeling of views and 
tablespaces, and data storage modeling for 
DB2, Oracle, SQL Server, and SQL Server 
2000. Contact for pricing. 
Rational Software 
Phone: 800-728-1212; 408-863-9900 
Web: www.rational.com 

ScheduleX 8.0 

ScheduleXS.O combinesfive lightweight(ATL) 
components for calendar, task management, 
and scheduling applications. Advanced Cal- 
endar, DayView, and TaskPad components 
letyou create Personal Information Manage- 
ment (PIM) software, project management 
and tracking, or any application that requires 
advanced scheduling. New features in ver- 
sion 8.0 include a configurable display, sup- 
port for international date formats, custom- 
ization of date separators, and the ability to 
choose the time display style. $395. 
Infragistics 
Phone: 800-231-8588 
Web: www.infragistics.com 

Team Remote Debugger 2001 

Team Remote Debugger 2001 lets you trace 
any number of code units of any kind (ASP, 
MTS, T-SQL, C0M+, ActiveX EXE, DLL, COM, 
Thread, or CFMLI written in any language 
(ASP, VB, VC++, Delphi, T-SQL, VJ, or CFML) 
residing on multiple shared and dedicated 
servers at the same time, without the need to 
attach to process. Features include the abil- 
ity to pass messages from remote code units 
to local machines, the ability to pass dialogs 
from remote code, remote code debugging, 
debugging on multiple servers, and collabo- 
rative team debugging. Contact for pricing. 
Spline Technologies 
Web: www.remotedebugger.com 

VersionStamper 6.5 

VersionStamper 6.5 is an ActiveX control that 
detects component version incompatibilities 
on end-user systems. It lets you create self- 
updating apps with support for the Internet 
and intranet. The program includes both 16- 
bit and 32-bit COM/ActiveX OCX controls, 
and it works with all COM/ActiveX control- 
compatible development environments. New 
features in version 6.5 include the ability to 
include custom messages for file conflicts in 
a file list, support to run the Conflict Wizard in 
batch mode to generate or update the refer- 
ence file list, support for scanning Wise and 
InstallShield installation scripts to generate 
the reference file list, and updates to the 
VersionStamper Internet components to sup- 
port proxy servers. $249. 
Desaware 
Phone: 408-377-4770 
Web: www.desaware.com 
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Get Financial 
News FAST 



The Organization of the Petroleum Exporting Countries (OPEC) 
and Austrian national newspapers are quick to gather their 
financial and world news using a Visual Studio solution called FAST 
(Financial Access Storage and Transfer system). 

FAST is a back-office application that acquires data from the 
well-known Reuters news service — either by satellite or land line — 
and stores it in a database. It then delivers the data to the user either 
in raw XML or in formatted Extensible Stylesheet Language (XSL) 
through HTTP, FTP, Simple Mail Transfer Protocol (SMTP), or 
Short Message Service (SMS). FAST provides an "easy way to work 
with Reuters financial data," says sole developer Richard Prinz of 
Regionale Informations Systeme GmbH (RIS) in Wiener Neustadt, 
Austria. Users can run the app in the background as a service or in 
the foreground as a console. 

RIS uses FAST internally, delivering the output to subscribing 
customers. But the company will soon sell it to users who want to 
process Reuters data themselves. The 20 MB app, consisting of 20 
DLLs and six EXEs, took Prinz one and a half years to develop. He 




For more information on FAST, e-mail Richard Prinz at Bb M 

richard.prinz@risnet.at. B 

used Visual Basic 6.0 for 80 percent of the solution, and Visual C++ 
and Visual J++ for the rest. FAST supports Microsoft Access and 
SQL Server databases, and will support Oracle in the future. 

Prinz used Reuters' Source/Sink Lib (SSL) development toolkit 
to build FAST, as well as "lots of information from MSDN and 
[the Microsoft] Knowledge Base," he says. He's most proud of the 
app's flexibility and was most challenged by its "horrible" multi- 
threading issues. 

In the future, Prinz would like to add features for statistical data 
analysis and mobile usage. He's also actively evaluating Visual 
Studio .NET: "We have already started some development with the 
beta version and are satisfied with the results ... in about a year, if all 
goes well, we'll have a .NET version available." — Nina Goldschlager 



Handhelds Visit the 
Doctor's Office 



Handheld computers seem to be popping up everywhere now — 
including the doctor's office. Typically, doctors meeting with 
patients dictate to a recorder or scribble notes on a pad. After the 
visit, someone transcribes the notes, then a medical coder reviews 
them and applies appropriate codes for billing. This system can be 
time-consuming, costly, and error-prone. 

PICOS, based in Sterling, Va., has circumvented this process 
with the Dictation Engine — part of PICOS' Total Practice Man- 
ager (TPM) suite, which performs all the tasks needed at a doctor's 
office, including scheduling, billing, purchasing, and inventory. 
Physicians at Dulles Orthopedics Group — a beta test site in 
Sterling — employ TPM on their Fujitsu Stylistic LT C-500s. As 
doctors meet with patients, they point-and-click through a series of 
logically displayed questions and answers, many displayed as 
detailed, high-resolution, 3-D graphics of the human anatomy. 
Once doctors finish their exam, the Dictation Engine produces a 
readable dictation that becomes part of the patient's history, as well 
as codes that meet industry standards for billing. Only a simple 
review and approval from billing personnel are needed to send the 
claim to the patient's insurance company. 

Stephen Mallette, PICOS' chief information officer, designed 
and developed the Dictation Engine in VB6 over a period of five 
months. System developer James Policano implemented the app in 
its host application, TPMVisit, a module of TPM. Satish Unni, 




For more information on the Dictation Engine, visit 
PICOS at www.picosinc.com, or reach Stephen 
Mallette by e-mail at smallette@picosinc.com. 



system analyst, gathered and documented the logic that drives the 
engine. The Dictation Engine comprises 1 class modules and 1 5 
forms (roughly 750 possible forms if you count those generated 
dynamically from the logic files). 

Mallette is proud that "the project came in on time, under 
budget, and with all requested functionality present." He adds: 
"The key to our success was not underestimating the level of effort 
required." Future plans include adding logic files for other medical 
specialties besides orthopedics. Another possibility: developing a 
logic file for capturing sporting-event statistics. — Nicole Pizzurro 

To submit proposals for VS All-Stars, send an e-mail to vsmedit® 
fawcette.com. 
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The company 

continues to grow and grow. And your system's transaction rates 
are climbing in lockstep with it. A big deal, for sure-but nothi 
to get anxious about. That's because SQL Server 2000 offers 
scalability for even the most demanding environments. So you 
know that no matter how much— or how fast— your system needs to 
expand, you'll have the tools to handle it. 

Part of the flexible Microsoft .NET Enterprise Server family, 
SQLServer 2000 recently achieved 20,000 SAP Standard Sales 
and Distribution (SD) Application Benchmark Users with a response 



SQL SERVER 2000 BENCHMARKS 

Application Workload ; World Record Result! 

SAP ft/3 Sales A Distribution i 20,000 concurrent users 



time of 1.91 seconds on 
a 32-processor Unisys 
ES7000 system running 
as the database server 
in a R/3 4.6C 3-Tier environment, surpassing a result achieved 
with Oracle 8.1 running on a Sun system with 64 processors.* 
In addition to world-class performance, SQL Server 2000 has 
price/performance numbers that are 2.5 times better th 
the closest competitor.* Add to that native XML support in 
SQL Server 2000 and you've got the database that's ready to 
handle Web-enabled enterprise applications far into the future. 



To get the full story on Microsoft SQL Server 2000 scalability, go to 
microsoft.com/sql/worldrecord Software for the Agile Business. 
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Pointers Add 
Power and Safety 

VB.NET comes as close to having pointers as VB ever has, 
while making memory manipulation safer at the same time. 
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by Robert Teixeira 

any VB programmers are concerned and confused about .NET's managed 
I memory model. Perhaps this is due partly to marketing campaigns that put 
the spotlight on .NET's Web and distributed computing features. But make no 
mistake: VB's ability to work with the Windows system at a low level, and work 
with unmanaged code from external libraries, has never been better. I demon- 
strated some of VB. NET's powerful new features in this area in my "Breaking 
API Barriers" article (see Resources), but that was only the tip of the iceberg. 



In this article, I bid farewell to CopyMemory (also 
known as the RtlMoveMemory API function) and 
showyou VB . NET's amazing new power over memory 
and pointers. That power is found in four new tools: 
IntPtr, .NET's platform-dependent representation 
of a memory address; GCHandle, which helps you pin 
and retrieve the address of data in the managed 
memory heap; the Marshal class, the one-stop shop for 
all your memory allocation, cleanup, and manipula- 
tion needs; and Delegate, .NET's representation of a 
function pointer. 

It's worth going over a few safety issues before you 
dive into .NET's new pointer features. I covered one of 
those issues in my August article, but I'll restate it here 
because it's worth review within this context. An 
automatic garbage collector (GC) maintains the man- 
aged heap: It compacts unused space and readjusts any 
managed references to the memory that was moved. 
Because of its dynamic nature, you need to take extra 
precautions whenever you want to capture an address 
within the managed heap. This involves the act of 
"pinning," which I'll revisit later in this article. 

The next safety issue relates to data integrity. 
When you take the address of a piece of data within 
the managed heap and pass that address to 



unmanaged code (any code written outside of.NET) , 
the .NET system can't guarantee the integrity of 
your data because the unmanaged code can do 
whatever it wants to the data without considering 
safety. Therefore, the compiler marks any opera- 
tions that do this (using API function calls, for 
example) as unverifiable. 

The last safety issue involves trust and permis- 
sions. The .NET system assures that its elements 
won't compromise your computer's security. For 
example, it knows which resources require file-system 
access and allows you to grant or deny the use of this 
resource depending on where the code came from. 
However, the .NET system has no way of knowing 
what resources will be accessed by unmanaged code, 
or how maliciously the unmanaged code might use a 
given resource. What's more, by manipulating point- 
ers directly, it's possible that the data or functions of 
a component marked as safe could be inadvertently or 
intentionally replaced by more malicious code — one 
more reason that calls to unmanaged code and direct 
pointer manipulation are marked as unverifiable. 

If you decide to work with direct memory ma- 
nipulation in VB.NET, the first thing you need to 
understand is the IntPtr type. IntPtr is a structure that 
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represents both addresses and handles (most handles are pointers to ' pin variable and create 

Windows pointers). IntPtr instances are also platform-dependent ' GC handle instance 

(or independent, depending on your point of view). On a 32-bit Dim gh As GCHandle = GCHandle.Al loc 
system, IntPtr is 32-bit, while on a 64-bit system, IntPtr is 64-bit. (MyString. GCHandleType. Pinned) 

The benefit is that you don't need to change or recompile your code 

for both platforms. Any function within the .NET Framework that ' get address of variable 

exposes a way to work with addresses and handles uses the IntPtr Dim AddrOfliyStri ng As IntPtr =_ 
type. Such functions are marshaled to unmanaged code simply as gh.AddrOfPinnedObjectt ) 
the internal address number, meaning you can pass a variable of 

IntPtr type ByVal to any unmanaged code that expects a pointer. So Consol e . Wri teLi ne _ 

the good news is that, although you can't use this in VB.NET: (AddrOfMyString.ToStringt ) ) 



Dim 1 pMyVari abl e As Void * 

this works brilliantly: 

Dim lpMyVariable As IntPtr 

Note that there was no IntPtr type in beta 1 — instead, functions 
that worked with pointers and handles used the Integer type. The 
IntPtr type has a ToInt32 method that converts the address to an 
Integer, but that can and will cause an Overflow exception on a 64- 
bit system. IntPtr also has a ToInt64 method, but you'll have to keep 
track of the platform if you want to do these conversions. 

Get a Handle on the Garbage Collector 

Next, let's examine how you place the address of a variable into an 
IntPtr. You use the GCHandle class, which has an AddrOf- 
PinnedObject method that returns an IntPtr for a variable. You 
must "pin" the data before you can get this address. This prevents 
the garbage collector from moving the data inadvertently while 
you're referring to the original address. This code pins a variable, 
displays its address on the console window, and frees the handle: 

' dim managed variable 
Dim MyString As String 



1 free the handle and unpin variable 
gh. Free( ) 

Freeing a GCHandle as soon as you're done using it minimizes the 
impact on garbage collection. As a rule of thumb, this code shows 
the standard way to capture the memory address of a managed 
object. Note that you don't necessarily need to use this method to 
pass the address of a variable to an unmanaged function (such as a 
Windows API function). VB uses the .NET PInvoke service to pass 
parameters to unmanaged functions, and this feature has greatly 
enhanced VB's ability to pass data and addresses seamlessly to such 
functions. In this case, if you wanted to send the string's pointer to 
an external unmanaged function, you would be better off passing it 
in the parameter list as a String and using the MarshalAs attribute 
to specify the type of string. PInvoke takes care of the pinning 
automatically (see the "Break API Barriers" article for more details). 

Be careful when you use value types, which are usually primi- 
tives or simple data types such as Integers. To utilize polymor- 
phism in .NET fully, a value type needs to be able to work as 
object. VB.NET uses a technique called boxing to accomplish 
this. A value type is boxed when you implicitly or explicitly cast it 
as an Object in VB.NET. Therefore, value types are boxed when 
you use the Alloc method of the GCHandle class, because the 
Alloc method accepts an Object type parameter. If the address is 



Process 1 



Memory-Mapped File 
View 1 




Process 2 



View 2 



View 3 




Figure 1 Share Memories Between Processes. Memory-mapped files are a powerful technique you can use to share "memory" between 
different processes. Processes can map to the same view or different views, or they can even have overlapping views. 
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being passed out, the unmanaged code still sees the correct value. 
However, if the unmanaged code writes back to the address, the 
new value won't carry over to the value type itself. This scenario 
is the same in C#, and its documentation states that if you need to 
write back to the value, you need to start off with an object instead. 
It looks like this in VB: 

Dim MyVariable As Object = 123 

The integer value type is cast to an object and boxed, and you can 
now pin the object representation of the integer. The value remains 
unchanged if you write back to this address. The object can then be 
cast back to an integer if needed. However, as I mentioned earlier, 
if you need to pass the address of a value type to unmanaged code, 
PInvoke is the most efficient way to do it — in other words, you pass 
the parameter ByRef to the unmanaged code. 

Memory Manager With Muscle 

You now know how to use the IntPtr type and capture the address 
of a managed variable, but addresses aren't really useful unless you 
can do something with them. If you need the power of direct 
memory manipulation, then the Marshal class is your friend. This 
class has nothing but Shared (Static) functions, most of which serve 
as memory-management utilities. An added benefit of the Marshal 
class memory manipulation methods is that they're much safer to 



use than arbitrary calls to something like RtlMoveMemory. Your 
need for this type of direct memory manipulation should be 
diminished in VB.NET, but later in the article I provide some 
examples of cases where you'd want to use it. The Marshal class 
includes several features worth mentioning. It enables you to 
allocate memory, as well as to read/write simple data, strings, user- 
defined types, and array data. 

You can allocate memory on the unmanaged heap, fill this 
memory however you like, and pass its address to unmanaged code. 
The Marshal class has two methods to allocate memory: 
AllocHGlobal, which allocates memory on the native heap by using 
the GlobalAlloc function internally; and AllocCoTaskMem, which 
is similar but instead uses the COM memory manager (CoTask- 
MemAlloc). Both functions have one parameter, the number of 
bytes to allocate. Both functions return an IntPtr, the base address 
of the newly allocated buffer. To free the memory, you use the 
FreeHGlobal or FreeCoTaskMem methods, depending on which 
allocation method you used. Each of these functions has one 
parameter, the address to the newly allocated buffer returned by the 
allocation functions. 

Use the WriteByte, Writelntl6, Writelnt32, or Writelnt64 
methods to write simple numeric data to an unmanaged buffer. 
Think of these as safer and more convenient versions of 
CopyMemory (RtlMoveMemory). Each of the functions takes as 
parameters the destination address of the write operation and the 

numeric value you want to write. These 

functions are also overloaded to allow an 
optional third parameter indicating an off- 
set from the address provided, which can 
be useful if you're attempting to fill memory 
with arrays of elements or fields of a struc- 
ture, for instance: 
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' allocate some memory and get its address 
Dim MyPointer As IntPtr = _ 
Marshal .Al 1 ocHGl obal (4) 

' write the number 255 to that address 
Marshal .WriteInt32(MyPointer. 255) 

' some more code here (call to 
' unmanaged code for example) 

' free memory 

Marshal . FreeHGl obal (MyPointer ) 

You can also use the address provided 
by unmanaged code instead of allocating 
your own: 

Dim MyPointer As IntPtr = New _ 
IntPtr( [insert integer address 
from unmanaged code here]) 

Marshal . Wri tel nt32 ( MyPoi nter . 255) 

The reverse is also possible: You can 
read simple numeric data from an IntPtr 
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address using the ReadByte, Readlntl6, Readlnt32, and Read- 
Int64 methods: 

Dim Mylnteger As Integer = Marshal . ReadInt32(MyPoi nter ) 

Read/Write Strings 

Reading and writing strings is similar to reading and writing simple 

numeric dm with one minor exception: Yon don't allocate memory 

first, then write a string to it. Instead, the act of creating a string in 
unmanaged memory allocates the space and returns the string's 
address. There are seven write methods: StringToBSTR, String- 
ToCoTaskMemAnsi, StringToCoTaskMemUni, StringToCo- 
TaskMemAuto, StringToHGlobalAnsi, StringToHGlobalUni, and 
StringToHGlobalAuto.The StringToCoTaskMemxxx functions write 
string data to COM allocated memory, while StringToHGlobalxxx 
functions write to the native unmanaged heap. Functions ending in 
Ansi write single-byte ANSI strings. Functions ending in Uni write 
double-byte Unicode strings. The functions ending in Auto write 
ANSI or Unicode strings, depending on the operating system: ANSI 
strings on Windows 98 and Me, Unicode strings on NT-based 
platforms (Windows NT 4.0, 2000, and XP). StringToBSTR writes 
an Automation BSTR, which is analogous to using the SysAllocString 
function. Each of these functions accepts a string as an input argument 
and returns a pointer to the resulting string: 

Dim MyStrPointer As IntPtr = _ 

Marshal . Stri ngToHGl obal Auto( "Hello World") 
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Four read methods — PtrToStringAnsi, PtrToStringUni, PtrTo- 
StringAuto, and PtrToStringBSTR — read the data at a given ad- 
dress and create a managed String object containing a copy of the 
characters. Use PtrToStringAnsi if the unmanaged string is ANSI, 
PtrToStringUni if the unmanaged string is Unicode, or 
PtrToStringBSTR if the unmanaged string is of BSTR type. PtrTo- 
StringAuto assumes the unmanaged string is ANSI on a Windows 

18 or Me system, and Unicode on a Windows NT { 0, 2000) or XP 

platform. PtrToStringAuto actually calls PtrToStringAnsi or 
PtrToStringUni, depending on the operating system. Each func- 
tion is also overloaded to accept an optional number of characters 
to copy. If you don't provide the number of characters, the function 
looks for a terminating null character: 

' copy entire string 

Dim MyString As String = _ 

Marshal .PtrToStri ngAuto(MyPoi nter ) 

' copy first 5 characters 

Dim MyString As String = Marshal . PtrToStri ngAuto 
(MyPointer, 5) 

To free the unmanaged memory buffer holding a string, you call 
either the FreeHGlobal or FreeCoTaskMem member. To free a 
BSTR created with StringToBSTR, you call FreeBSTR, which in 
turn calls the FreeSysString function. 

You write a Structure (user-defined type) to unmanaged memory 
by using the StructureToPtr method. This method 
requires you to have a memory buffer allocated 
ahead of time. It takes three parameters: the 
Structure you wish to write, the address (IntPtr) 
of the memory buffer, and a delete flag. Setting 
the delete flag to True wipes and frees any existing 
data from the buffer. This is important, because 
you can cause memory leaks by failing to delete 
the existing buffer space. For example, if one of 
the fields of the structure is a reference to another 
structure or string, the data being referenced by 
the field won't be freed if the parameter is set to 
False. Also note that Structures are copied to 
unmanaged memory using specific formatting 
(which you can control optionally), and the 
unmanaged copy might not look exactly like the 
managed representation (refer to the "Break API 
Barriers" article for more information). Use the 
SizeOf method to determine the number of bytes 
required for the buffer: 
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Dim MyVariable As Point 
MyVariable.X = 100 
MyVariable. Y = 250 

Dim MyPointer As IntPtr = _ 
Marshal .Al 1 ocHGl obal 
(Marshal . Si zeOf ( MyVari abl e ) ) 

Marshal. StructureToPtrt My Variable, 
MyPointer, False) 
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Use the PtrToStructure method to reverse 
the process and read a structure from 
unmanaged memory. You can use this 
method either as a Function that returns a 
copy of the structure based on Type, or as a 
Sub that fills a structure parameter. Note 
that PtrToStructure returns an Object type 
reference, and with Option Strict On, you 
must cast to the structure type (by using 
CType, for example): 

Dim MyPoint As Point 
MyPoint - CType(Marshal . PtrToStructure _ 
(MyPointer. GetTypet Poi nt ) ) , Point) 

Read/Write Array Data 

Reading and writing array data is especially 
valuable when you need to stream binary 
data. The Copy method does both reads and 
writes, depending on the parameters you 
pass to it. If you want to write the data, you 
need to allocate some buffer space first, just 
as you would with strings. Next, you call the 
Copy method and pass the array itself, the 
index in the array of the element you want to 
start the copy with, the destination address 
(IntPtr resulting from the allocation), and 
the size of the buffer: 

Dim MyData(255) As Byte 

' insert code here to fill byte array 

Dim BufferAddress As IntPtr = _ 

Marshal . Al 1 ocHGl obal ( 256) 
Marshal .CopytMyData, 0, BufferAddress. 256) 

To read an array from unmanaged 
memory, call the Copy method and pass the 
address of the buffer (IntPtr), the array you 
want to fill with the data from the buffer, the 
index of the array you want to start copying 
into, and the size of data you want to copy: 

Dim MyData(255) As Byte 

Marshal Xopy( BufferAddress. MyData, 0, 256) 

The Marshal class has many more meth- 
ods, but most of them are utilities that aid in 
interoperation with COM code. 

I promised earlier that I would explain 
some of the uses for this type of direct 
memory manipulation, because it usually 
is not necessary if all you're doing is calling 
Windows API functions from .NET. One 
of the reasons is that to pass the address of 
a variable to unmanaged code, you need to 



Your Program 



Pointer to Base Address 




0.5 MB Mapped "View" 



Figure 2 Peer Into Files. You can use memory-mapped files to get a small view of large files. 
This helps you avoid loading the entire file at the same time and can be useful for looking at 
one record or a page of records in an extremely large data flat file. 
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pin it first, as you've seen already. This is fine if you need that 
address for only a brief period. But what if some unmanaged code 
needs that address for a long time? Here, having pinned GCHandles 
can affect the performance and efficiency of the garbage collec- 
tion. In this case, you might be better off allocating space in the 
unmanaged heap, copying the data to that buffer, and passing the 
address of the buffer to your unmanaged code. 

Another reason for using the Marshal class is to do what it was 
intended for originally: creating custom marshalling routines. Back 
in the good old COM days, you could marshal data from your 
method calls, as long as they were native COM types. You wrote a 
custom marshaler if you needed to marshal custom types not 
covered by the default marshaler; one reason for doing this is to 
boost performance. In the .NET world, ifyouhavea type that needs 
to be handled in a particular way when being passed to unmanaged 
code, you need to do the same thing. Luckily, writing custom 
marshalers is considerably easier in .NET: You use the Matshal class 
to read and write the data to unmanaged memory. 

Performance is also a factor. Passing a lot of data back and forth 
berween managed and unmanaged memory incurs a performance 
penalty. If you have latge quantities of data that need to be handled 
by unmanaged code, it is better to allocate a buffer that the 
unmanaged code would use and read/write smaller individual pieces 
of data to that buffer. 
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columns, headers, column reordering, 
font selection, auto-completion, auto- 
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numeric fields, OLE drag & drop, 
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Control 
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bitmaps, icons, fonts, disabled tabs, 
shared controls, ToolTips, complete 
design-time support and much more. 
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So far, I've shown you how to work with memory addresses, 
allocate and free memory on the unmanaged heap, and read and 
write directly to memory. I've even given some brief examples of 
how these activities can be useful. Now I'm going to show you an 
example of a powerful technique: file mapping. After all, any article 
worth its salt has to have a cool and practical example, right? File 
mapping involves taking a "view" of a physical file and making it 
look like regular memory in your process. This is useful for several 
reasons. For example, you can create a shared mapped file, which 
allows different processes to view the same "memory" contents (see 
Figure 1). A process can have multiple views of that file, and other 
processes can have overlapping views as well. 

Another advantage of this technique: A process can look at 
literally gigabytes of data without having to load the entire contents 
at once (see Figure 2). Some "virtual" controls use this technique to 
display a window (view) of data to the user when the actual contents 
are much larger than would normally be acceptable to load at once. 

The full details of memory mapping are far greater than the 
scope of this article, so I'll focus on showing you how to create a 
read-only view into a text file (download Listing 1 ; see the Go 
Online box for details). The first thing you need is a file. Instead 
of throwing gobs of code at you and making things really confus- 
ing, I offer a simple example: Copy a large text file and rename it 
(in this case, my example uses the filename "temp.tmp"). 

You open the file with a FileStream 

object and thereby eliminate the need to 
call the CreateFile API function. You need 
to do this to get a handle to the open file. 
Next, call the CreateFileMapping API func- 
tion, which returns a FileMap handle. Now 
you're ready to create a view by calling the 
MapViewOfFile function, in which you 
specify the offset from the start of the file 
as well as the size of the view. The offset 
needs to coincide with the memory alloca- 
tion granularity of the system. 
MapViewOfFile returns the base address 
of where the data will appear in "memory." 

At this point, you can use that address 
along with the Marshal class methods I 
discussed in the previous section to read 
the data. If you had full memory mapped 
file capabilities in this example by creat- 
ing it with read-write access, you'd be 
able to write to that "memory" too using 
the Marshal class members. In this ex- 
ample, I simply read the entire view as a 
string and display it to the console win- 
dow. When you're done with a particulat 
view, you must close the view using the 
UnmapViewOfFile function. When 
you're finished with the file, you must 
close the memory map file handle using 
the CloseHandle function. 

With a little bit of extra work, you could 



Putting You In Control stf 



He* 







34 



Visual studio Magazine • October 2001 • www.vbpj.com • www.vcdj.com 



Active Reports 2.0 is an upgrade to our best-selling reporting component. Data Dynamics offers Active Reports 2.0 
in two editions to suit your development needs. Both editions build on trie power and ease of ActiveReports 1 .0 and add 
many new features and enhancements based on your feedback. 

Active Reports 2.0 Standard Edition now supports distributable XML report layouts, Active Scripting (VBScript/ JScript) 
events and expressions and XML data sources. Active Reports 2.0 Professional Edition adds a royalty-free customizable 
end-user report designer control. Now your users can experience the power of ActiveReports within your applications. 



CSS Styles ■ 
Report Explorer ■ 



ActiveX Host 



Rich Text Control 




Subreport Control 
XML Schema Tree 

ADO, DA0, RD0 and XML 

Lightweight Viewer 
Table of Contents 

Splitter and Thumbnails 



Syntax-highlighting Editor 




MHM* 


Product Catalog 




Product Category 




iodut! Mane: 
txtPradurm mm* ■::*•: 


f*odiK* JO Quantity. 'ti nil 
Sort hut ind Traders - 1 SI 


fOrrc 


1 : ■■- -vf ■ 

•' V"' ' 




"Tooe "' * tut i'aop*mnto ■ 




xanTHwwn 


npnFR form 


TlUDEta 







Icon 

Na> Button 

NDICWd 

Nrtutton 



0.1:1- fl-.fiieU 



top rii imnga^. 



" llnitHt fetkigt 



1 ■ 








Onfe porcS tart 

11 E».Sbotf>et*ll Tnen 

1 . ■ : a- - ■ n -■■ - Ttua 




trrf 


Ejt.wet«ij.visioje " raise 

End [f 
Sob 








1 



Data Access 
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Deployment 



Reports can be compiled for maximum security and 
speed. 

New! Report layouts can be distributed as XML-based 
report layout (RPX) files (application-host independent]. 
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ing support. 
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and HTML export filters. 
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bookmarks and embedded fonts. 



ActiveX Viewer 



• New! Multipage tfiumbnails. 

• New! Split views. 

• New! Ruler. 

• New! Text search. 



Pricing 
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Pointers and .NET Interop 



make a robust class to handle memory- 
mapped files and even provide stream access. 

Delegate Your Callbacks 

I'll mention one last .NET pointer feature: 
delegates, a powerful means of encapsulat- 
ing function pointers. Much has been writ- 
ten on delegates, but I'll make a token 
mention here, because an article about point- 
ers in .NET wouldn't be complete without 
them. Creating a delegate instance in VB is 
easy: You merely use the AddressOf opera- 
tor. When a delegate is passed to unmanaged 
code, it is marshaled as an address. If you do 
pass a delegate to an unmanaged function, 
make sure you declare a delegate variable 
first and assign the value of the AddressOf 
operator to that variable, which you can 
then pass to the unmanaged code. This 
keeps the delegate in scope after the call to 
unmanaged code. 

Delegates are interchangeable between 
functions, as long as the functions have the 
same signature — in other words, as long as 
they have the same number and types of 
parameters. Although the Delegate class is 
intended to be the primary mechanism for 
handling events in .NET, it also makes 
wiring up unmanaged callbacks simple. The 
biggest perk is that a delegate doesn't care if 



Robert Teixeira is a Florida-based consultant 
who is assessing VB's ability to not only 
support the next generation of applications, 
but to lead the way to them. You can reach 
him at robteixeira@msn.com. 



Use these DevX Locator+ codes at 
www.vbpj.com or www.vcdj.com to 
go directly to these related resources. 

VB0110 Download all the code for 
this issue of VSM. 

VB0110RT Download the code for 
this article separately. This article's 
code includes Listing 1 , which shows 
you how to create a read-only view 
into a text file. 

VB01 10RT_T Read this article online. 
DevX Premier Club membership is 
required. 

Want to subscribe to the Premier 
Club? Go to www.devx.com. 



your function is a static (Shared) function, 
as a VB6 module function would be, or if it's 
an instance method, like a VB6 class func- 
tion. The benefit is that you can wire a 
callback to a class method simply by using a 
delegate variable with the result from an 
AddressOf expression. Matthew Curland 
wrote an excellent column on duplicating 



this functionality for VB6 (see Resources), 
but it's a no-brainer in .NET. 

The .NET architecture lets you write 
powerful managed code. However, if you 
need to reach beyond this to unmanaged 
code, the new tools I've covered in this 
article, in conj unction with PInvoke, should 
prove invaluable. < 
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Enhance Performance 
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Use ADO Connection objects to achieve better 
performance and scalability in n-tier applications. 
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anaging precious client and server resources efficiently is the key to making 
n-tier applications more scalable. Using ActiveX Data Objects (ADO) 
Connection objects can help your application respond faster and scale up more 
easily to hundreds of users in a corporate environment. In this article, I'll show 
you an efficient, flexible way to use ADO connections from Visual Basic. You'll 
create two projects, one COM-based and the other based on COM+ or 
Microsoft Transaction Server (MTS). 



An ADO Connection object represents a unique 
session with a data source. In the case of a client/ server 
database system, it might be equivalent to an actual 
network connection to the server. You'll take advan- 
tage of ADO's connection-pooling capabilities. Con- 
nection pooling enables an application to use a con- 
nection from a group of connections you don't need 
to reestablish for each use. Once you create a connec- 
tion and place it in a pool, an application can reuse 
that connection without performing the complete 



Resources 



•"Pooling in the Microsoft Data Access 
Components" by Leland Ahlbeck and Don 
Willits. Includes a link to download the MDAC 
Pooling Toolkit: http://msdn.microsoft.com/ 
library/techart/pooling2.htm 

• Professional MTS MSMQ with VB and ASP by 
Alex Homer and David Sussman (Wrox Press, 
1998, ISBN. 1861001460) 

• Microsoft Universal Data Access download 
page: www.microsoft.com/data/download.htm 



connection process. By using the technique presented 
in this article, you can allow many applications or 
business objects to share the connection parameters at 
the same time, offering centralized management of 
Connection objects. 

To get started, think about how the client part of 
a typical two-tier client/server application works. 
When it requires data from a data source, a client 
application first opens an ADO connection, then 
opens a recordset against the connection and retrieves 
the desired data. The application then updates data or 
executes commands against the database by using the 
ADO connection. At any time — and depending on 
how many data forms a client has opened — you 
might have several active ADO connections to the 
same data source. Each connection consumes memory 
and occupies server resources. 

This process is similar in a three-tier application. In 
the middle tier, the business objects need to retrieve 
data from the data source and pass it to the presentation 
objects. The presentation objects in turn manipulate 
the data and use the methods exposed by the business 
objects to update the data in the data source. In this 
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VB6- Understand the MDAC Toolkit Approach 



mm 



Dim globalCN As ADODB. Connection 
Pri vate Sub Form_Load( ) 



Set globalCN = New ADODB . Connect! on 
globalCN. Open "Provider=SQLOLEDB . 1 ; " & _ 
"Password=; Persi st Security Info=True:" 
"UserID=sa;Initial Catal og=YourDB ; " & _ 
"Data Source=YOUR_SERVER" 

End Sub 

Private Sub Command2_Cl i ck( ) 
Dim cn As ADODB. Connection 
Dim dblStart As Double 
Dim dbl End As Doubl e 
dblStart = Timer 

'You can do performance testing by changing 
'the number of times the following loop is 
'executed via an input textbox 
For i = 1 To txtLoop.text 



. . ■ 

Set cn - New ADODB. Connection 
cn.Open "Provider=SQLOLEDB. 1 ; " & 

" Password-; Persi st Security Info-True: 
"UserID=sa;Initial Catal og=YourDB ; " & 
"Data Source=YOUR_SERVER" 



txtSampl e .Text 
cn. Provider • 
"Version:" & 



- " Provi der : " & _ 
■ Chr(13) & Chr(lO) & 
cn. Version 



Set cn 
Next i 



Nothi ng 



dbl End = Timer 
'display the result 

txtTime.Text = Formattdbl End - dblStart. 

"0000.000") & " seconds" 
MsgBox "Loop Completed !" 

End Sub 



Listing 1 This sample test form demonstrates the MDAC Toolkit's approach. The form has a command button that, when clicked on, ex- 
ecutes a loop through a textbox as many times as the user specifies. Each loop iteration opens a new ADO connection, retrieves the Provider 
and Version properties, and displays them in a textbox. When the loop code finishes executing, another textbox on the form displays the 
elapsed time. 
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Figure 1 How the ActiveX DLL Works. The ActiveX DLL you create in this article is the connection to all data operations requested by 
several types of applications. You can use the DLL from traditional client/server applications, n-tier applications, or ASP-based Web applica- 
tions. The DLL provides a single source for holding the connection parameters to the database, and improves performance and increases 
scalability by reducing resource requirements. 



case, the middle-tier objects open and manage all the required ADO 
connections. Usually, each middle-tier object opens and closes its own 
ADO connections as needed. If the presentation layer calls more than 
one method of a business object at the same time, the middle-tier 
object can open multiple connections simultaneously, resulting in a 
situation similar to the one described for a two-tier application: The 
application uses more memory than necessary and opens more 
resources than necessary on the data server end. Also, the application 



replicates the connection-specific parameters (OLEDB Driver, User, 
Password, Database, and Server) inside all business objects, making it 
difficult to maintain the business objects in case users or developers 
need to change these parameters. 

Solve the Connection Problem 

Microsoft offers one solution to this connection problem in its 
Microsoft Data Access Components (MDAC) Connection Pool- 
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Set cn = New ADODB. Connection 


Dim cn As ADODB. Connection 




cn.Open Provider-SQLOLEDB. 1 ; & _ 


Dim dblStart As Double 




"Password=;Persist Security Info=True;" & _ 


Dim dblEnd As Double 




"UserID=sa ; Initial Catal og=YourDB ; " &_ 


dblStart = Timer 




"Data Source-YOUR_SERVER" 


'You can do performance testing by changing the 






'number of times the following loop is executed 




End Sub 


'via an input textbox 






For i = 1 To txtLoop.Text 




Private Sub CI ass_Termi natet ) 


'set a reference to the connection provided 




cn .Close 


'by the COM object 




Set cn = Nothing 


Set cn = provideCN. GetConnection 




End Sub 


'display some attributes of the connection 






' object 




Public Function GetConnectionf ) As _ 


txtSample.Text = "Provider: "& cn. Provider & _ 




ADODB. Connection 


Chr(13) & ChrUO) & "Version:" + cn. Version 




Set GetCN = cn 


Next i 




End Function 


dbl End = Timer 






'display the result 




'example usage of CN Li b . CN inside a VB form. Use 


txtTime.Text = Formatf dbl End - dblStart. _ 




'a similar technique to use this object inside 


"0000.000") 8. " seconds" 




'another COM business object to get a reference 


MsgBox "Loop Completed !" 




'to an ADO connection 


End Sub 




Dim provideCN As CNLib.CN 


Private Sub Form_Unl oad(Cancel As Integer) 






Set provideCN = Nothing 




Private Sub Form_Load() 


End Sub 





Listing 2 The COM DLL instantiates a new ADO connection upon initialization, and it returns a reference to it every time the calling applica- 
tion calls the GetConnection method. When there are no more instances of the COM DLL, the DLL destroys the ADO connection and 
releases memory. 



ing Toolkit. (The MDAC Toolkit consists 
of numerous code samples you can use as 
templates for adding pooling to your appli- 
cation, and for verifying and diagnosing 
performance issues that arise due to pool- 
ing.) The toolkit's solution is to use a 
globally declared ADO connection with 
Application scope. You open an ADO con- 
nection at the beginning of the application 
(for example, Form_Load event) and this 
connection stays open for the application's 
duration. In this way, the application holds 
an open connection for the length of its 
execution, regardless of whether it needs 
the connection. This keeps the ADO ses- 
sion pool active at all times (see Listing 1). 
However, this method doesn't do a good 
job of conserving memory and other re- 
sources at the client. Inside the OLEDB 
layer, the OLEDB connection pooling saves 
some server resources, but each open ADO 
connection on the client side consumes 
some memory. In addition, managing and 
cleaning up memory for all the connec- 
tions opened and closed during the test 



loop use many unnecessary CPU cycles. 

You should also avoid an alternative way 
of using ADO Connection objects: simply 
opening and closing ADO connections as 
needed. Initializing the ADO connection 
loses a lot of time, and this method doesn't 
take advantage of ADO and OLEDB's built- 
in connection pooling because no persistent 
connection is open. You'll also have net- 
work traffic problems and more CPU time 
consumed initializing and cleaning up the 
memory used by each connection on the 
client side. 

The best way to deal with connections is 
to create an ActiveX DLL (in-process server) 
that holds an open ADO connection and 
returns a reference to it as needed. This way 
to share an ADO connection between mul- 
tiple business COM objects fits well within 
an n-tier architecture where you deploy the 
objects in the business-logic layer sepa- 
rately from the presentation objects. The 
presentation layer on the users' desktops 
doesn't consume any database resources 
this way. 



This article's sample project compiles 
and deploys an ActiveX DLL named 
CNLib.CN together with the presentation 
layer, which can also stand in for middle-tier 
objects in an n-tier application (see Listing 2 
and Figure 1). The DLL opens an ADO 
connection in the Initialize event and re- 
turns a reference to this connection every 
time a client application calls the GetCon- 
nection method. The client application (or 
a business object) can open as many connec- 
tions as needed. However, each of these 
ADO Connection objects refers to an in- 
stance of the CNLib.CN you instantiated in 
the Form_Load event. 

I'll walk you through the code in more 
detail. First, you need to create the ActiveX 
DLL. Start by creating a new ActiveX DLL 
project in VB called CNLib and setting its 
property-threading model to be apartment- 
threaded. VB creates a class automatically; 
name it "cn. " Set the class's Instancing prop- 
erty to Multiuse and the MTSTransaction- 
Mode property to NotAnMTSObject, be- 
cause you won't be using MTS objects in 
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this example. Next, declare a variable inside 
the class that will serve as the ADO Connec- 
tion provider to the calling applications: 

Dim cn As ADODB. Connection 

In the Class_Initialize event, create an 
instance for the variable cn and open the 
ADO connection using various parameters. 
You might want to change the connection 
parameters to suit your needs or even use a 
Universal Data Link (UDL) file to provide 
these parameters: 

Private Sub CI ass_Ini ti al i ze( ) 
Set cn = New ADODB. Connection 
cn.Open " Provi der=SQLOLEDB . 1 ; "& _ 
Password-; Persi st Security 
Info=True;"& UserID=sa; _ 
Initial Catal og=YourDB ; "& 
Data Source=YOUR_SERVER" 
End Sub 

You should also remember to close the 
ADO connection and release all resources in 
the Terminate event that executes when all 
the calling applications finish using the 
ActiveX DLL: 

Private Sub CI ass_Termi nate( ) 
cn . CI ose 

Set cn - Nothing 
End Sub 

The only method offered by the Active X 
DLL returns a reference to the internal 
ADO Connection object. A calling applica- 
tion uses this reference in several ways I'll 
discuss later: 

Public Function GetConnection( ) As 

ADODB. Connection 

Set GetCN = cn 
End Function 

Test the DLL 

You're ready to test the ActiveX DLL from 
a calling application after you compile it. 
Use VB to create a standard EXE project 
with one form that uses the ActiveX DLL. 
You need to include the CNLib DLL you 
just created in the new project's References 
section to use the ActiveX DLL object in 
your project. Then you can declare a vari- 
able from the CNLib DLL in your form: 

Dim provideCN As CNLib. CN 



This variable is initialized in the 
Form_Load event. At this point, the ADO 
connection inside the DLL is instantiated 
with these parameters: 

Pri vate Sub Form_Load( ) 

Set provideCN = New CNLib. CN 
End Sub 



Create a command button and several 
textboxes on the form to test the ActiveX 
DLL and its performance. Your goal is to 
simulate a full-scale application where ADO 
Connection objects are created and destroyed 
all the time while serving the data operations 
the application requires. So, program a For 
Loop that uses an ADO connection con- 
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tinuously to retrieve certain parameters (you can substitute other 
data operations here, such as opening recordsets or calling stored 
procedures): 

For i - 1 To txtLoop.Text 

'set a reference to the connection 

'provided by the COM object 

Set cn = provideCN.GetConnection 
'display some attributes of the 
'Connection object 
txtSampl e .Text - "Provider: "& 

cn. Provider & Chr(13) & Chr(lO) 

& "Version:" + cn. Version 

Next i 

The value entered in a textbox on the form named txtLoop 
controls the number of iterations. Display the ADO Connection 
object's Provider and Version attributes in another textbox on the 
form named txtSample. During the For Loop, all ADO connections 
used through the variable cn point to the same Connection object 
in memory: the one instance of CNLib.CN you instantiated in the 
Form_Load event. Having all open ADO connections point to the 
same Connection object in memory offers significant savings in 
memory on the client side and in resources on the server side. Think 
of an enterprise-wide application where the average user has three to 
four VB forms — each using at least one ADO connection to 
manipulate data — opened at the same time, and several hundred 
users are accessing the system concurrently. Following this method, 
this application could open from 300 to 2,000 fewer connections at 
the same time. This results in an application that can scale more 
easily and work well under heavy usage. 

Another advantage of having all open ADO connections point to 
the same Connection object in memory: The connection parameters 
are located centrally inside one COM object. If any of these param- 
eters changes, you don't need to recompile the entire application, 
which you'd have to do if you used the MDAC Pooling Toolkit's 
method. The method in this article takes advantage of the COM 
architecture in an easy-to-use way from VB. In the future, you can 
change the connection parameters inside the ActiveX DLL object. 
You only have to parameterize the ActiveX DLL object to deal with 
different connection parameters for different business objects if you 
need to use several different access permissions patterns. 

Use MTS or COM* 

You can use MTS or COM+ to augment the performance advan- 
tages of using an ActiveX DLL to provide a reference to an open 
connection. You can use MTS' object-pooling capabilities to reduce 
resource overhead and enhance performance. Take advantage of 
MTS' object-management features by compiling the ActiveX DLL 
as an MTS object. You can give your object advanced security 
features and transactional capabilities, and you can deploy it easily 
in an enterprise-wide solution (download Listing 3 from the VSM 
Web site for an MTS implementation of the ADO Connection 
provider object; see the Go Online box for details). 

The MTS code is similar to the COM code, but it has a few 
substantial differences. The ActiveX DLL implements the 
ObjectControl interface that's required for interaction with MTS. 



It also requires you to declare a variable of type ObjectContext that's 
used for the stateless implementation: 

Implements ObjectControl 

Dim objObject As ObjectContext 

lailljCliliitiiiClisliiiraoi 



the same as in Listing 2, you need to add two events related to the 
MTS implementation: 

Private Sub 0bjectControl_Acti vatet ) 

Set objObject = GetObjectContextC ) 
End Sub 

Private Sub ObjectControl_Deacti vate( ) 

Set objObject - Nothing 
End Sub 

MTS calls the ObjectControI_Activate event when the ActiveX 
DLL object is instantiated, and calls and the ObjectControL 
Deactivate event when the object is destroyed. In addition to these 
two events, add one more MTS-related method: 

Private Function ObjectControl_CanBePool ed( ) As _ 
Bool ean 

ObjectControl_CanBePool ed - True 
End Function 

MTS calls the CanBePooled method to determine whether the 
ActiveX DLL supports object pooling. This is true in this case. The 
GetConnection function is also different from Listing 2: 

Public Function GetConnectiont ) As ADODB. Connection 

Set GetCN = cn 

'release context 

objObject.SetComplete 
End Function 

You call an additional line of code, objObject.SetComplete, to 
release the object context back to MTS. This allows MTS to make 
optimum use of resources. 

An MTS implementation is most useful in a three-tier architec- 
ture where you deploy the business objects using MTS on an 



Understand Threading Models 

A threading model is a set of rules describing the interaction 
of threading and COM that an object or a client follows. In the 
apartment model, the main rule is that a client application can 
call an object's methods only from the thread the object was 

created on. 

In the free-threading model, a client application can call any 
object method or COM function from any thread at any time. It's 
up to the object to serialize access to all its methods to whatever 
extent it requires to keep incoming calls from conflicting. Free 
threading provides the maximum in performance and flexibility. 
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Efficient ADO Connections J 



Method 1,000 loop iterations 10,000 loop iterations 20,000 loop iterations 



COM DLL CNLib 


0.187 seconds 


1.9 seconds 


3.9 seconds 


MDAC Toolkit approach 


0.250 seconds 


2.4 seconds 


4.8 seconds 



Table 1 The COM DLL Method is the Most Responsive. Here's a responsiveness comparison of the COM DLL you create in this article 
with Microsoft's MDAC Pooling Toolkit method. I tested 1,000, 10,000, and 20,000 loop iterations using the code in Listings 1 and 2. The 
COM DLL approach is 20 to 25 percent faster than the MDAC Pooling Toolkit method. Also, because the COM DLL returns a reference to an 
ADO connection, there's significantly less memory usage. 



Technical note: I performed all tests on a Dual Pentium III 500-MHz PC equipped with 512 MB of RAM, connected to a Dual Pentium III 600-MHz server equipped 
with 1 GB of RAM using a 100-mbps Ethernet LAN. The client ran NT 4.0 Workstation and ADO 2.6, and the server ran Windows 2000 Advanced Server and SQL 
Server 2000. 



Method Two application Four application Five application 





instances 


instances 


instances 


COM DLL CNLib 


2.5 seconds 


2.9 seconds 


3.3 seconds 


MDAC Toolkit approach 


3.2 seconds 


3.9 seconds 


4.8 seconds 



Table 2 Examine the Methods' Scalability. The response time changes when two, four, and five instances of the calling application are 
running at the same time and each instance goes through 10,000 loop iterations. The COM DLL method scales better than the MDAC Toolkit 
method. With two application instances opening and closing connections at the same time, the drop in performance is 31 percent for the 
COM DLL and 37 percent for the MDAC Toolkit approach. With four application instances, the COM DLL drops 52 percent and the MDAC 
Toolkit approach drops 63 percent in performance. With five application instances opened simultaneously, the COM DLL responds 73 
percent more slowly, but the MDAC Toolkit method takes 1 00 percent more time to respond. 



application server residing between the users' workstations and the 
data server. Again, imagine a corporate-wide solution where hun- 
dreds of users at once are accessing data and services. All business 
objects can use an instance of CNLibMTS.CN to get a reference to 
an open ADO connection. The resource savings on the application 
server and on the data server can be significant and allow the 
application to serve user requests more efficiently. Additionally, if 
the connection-specific parameters change, you need to modify 
only one object to make that change. Maintenance is much easier 
with this method. 

Create a Stateless Implementation 

A proper implementation of an MTS object has to be stateless for 
MTS to reuse the instance of the component and associate it with a 
different context. A release of the object context (that is, stateless 
implementation) happens when you call the SetComplete or the 
SetAbort method inside the objects' methods. Although your imple- 
mentation maintains some state, this state is always the same no 
matter how many applications are using the MTS object and calling 
its methods. The ADO Connection object opened in the Initialize 
event stays as is until your application terminates the last instance of 
the MTS object. Any application, business object, or data access 
object calling the MTS object's GetConnection method always 
receives the same result; the order of invocation doesn't matter. 

Unfortunately, in VB6's implementation of the MTS object, 
you can't use the MTS object-pooling capabilities (derived through 
the "stateless" implementation) because the COM object is apart- 
ment-threaded and not free-threaded (see the sidebar, "Understand 
Threading Models") . However, you'll be able to do this in VB.NET 
when it's released. In the meantime, you can still take advantage of 
MTS' advanced security features and its transactional and central- 
ized deployment capabilities. 
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Now, compare the DLL you've created with Microsoft's MDAC 
Pooling Toolkit method in terms of responsiveness, scalability, and 
ease of use, and you'll see that the COM DLL approach is the fastest 
and most scalable (see Tables 1 and 2). The COM DLL methods 
allow you to control connections centrally and let business-layer 
objects be independent of the data source being used. Each business 
object can get a reference to a connection opened by the COM DLL. 
In contrast, the MDAC Toolkit method hides the connection- 
specific parameters (OLEDB Driver, User, Password, Database, and 
Server) inside the application itself. Therefore, changing the data 
access methods results in changing the presentation objects, violating 
one of the primary principles of building n-tier applications. 

In contrast, the COM DLL approach allows you to design an 
enterprise-wide application that makes more efficient use of valu- 
able client and server resources, and at the same time allows changes 
to the data source without affecting either the presentation or the 
business-object layer. 

You've now learned how to encapsulate an ADO connection 
within a COM object. Your data access objects, business objects, or 
presentation objects can share this COM object, making efficient 
use of one of the most important ADO resources. You can often 
apply the methods in real-life applications. 

You might have an Active Server Pages (ASP) Web application, 
such as an e-commerce store or an online reporting system, in which 
several ASP pages need to access data from a data source. Have each 
ASP page use a connection provider COM object to get a reference 
to an active ADO Connection object. You can then use the ADO 
Connection object to execute commands such as stored procedures, 
retrieve data through recordsets, or pass it as a parameter to other 
business objects that accomplish data-relared tasks. 

This method consumes fewer resources while thousands of users 
access the ASP pages from the Internet. This is especially true if each 
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Efficient ADO Connections 

\ 



user opens several ASP pages at the same time. Compare this 
situation to the traditional approach of opening a separate ADO 
connection on every ASP page that accesses data. You can expect a 
significant improvement in response time using the shared COM 
object, achieving much greater scalability. You should implement 
the connection provider COM object as a Session object because 
application-level objects shouldn't be apartment-threaded. They 
should be both-threaded (that is, capable of apartment-threaded 
and free-threaded execution), while session-level objects can be 
apartment-threaded (download Listing 4). 

You can also use your COM object in an n-tier application in 
which several business or data access objects need to access and 
manipulate data from a data source. Each object needs to open 
several recordsets, execute commands, and return results to the 
presentation-layer objects. To perform these tasks, all these objects 
need to open one or more ADO Connection objects to access and 
manipulate data from a data source. Assume you're deploying all 
these objects using MTS or COM+ on a particular object server, and 
also assume the presentation layer, which resides on the worksta- 
tions of hundreds of corporate users, is using them. Compare the 
scenario of having all these objects use each of their own ADO 
Connection objects vs. sharing the one provided by the connection 
provider COM object. As in the preceding example, the system's 
performance and scalability increase greatly by using the connection 
provider COM object to provide a reference to an existing ADO 



connection. Maintenance and change management are much easier 
because all the connection-specific parameters are located inside one 
object instead of being scattered inside several business or data access 
objects, van 



Dimitrios Tsonis is the chief software architect at Berland Tech- 
nologies Inc. in Culver City, Calif. His main focus is on designing 
and implementing highly scalable n-tier applications using Win- 
dows DNA technologies. You can reach him bye-mail atdimitrios® 
berlandtech.com. 
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Clear Common 
C# Hurdles 



Avoid the most common gotchas you're likely to 
encounter when using Microsoft's new C# language. 



□ VB.NET 

□ SQL Server 2000 

□ ASP .NET 
fflTXML 

□ VB6 



by Don Preuninger and Joe Dour 

Nothing's perfect, and that includes programming languages. C# promises to 
simplify life for C++ developers, giving them most of the power and 
flexibility they're accustomed to, but with RAD advantages that have been part- 
and-parcel of the Visual Basic experience for years. 



Microsoft: has made significant progress with C#, 
but, as with any programming language, you as a 
developer can still encounter some significant issues 
and gotchas that pop up from time to time — issues 
that can give you headaches or indigestion if you're 
unprepared for them. At the same time, most of these 
issues are surmountable with a little forethought. 
We've been developing components for the .NET 



platform for more than oneandahalf years now, and 
we've encountered a healthy number of stumbling 
blocks that have impeded our progress along the way. 
In this article, we'll share some of our insights on 
working with C#, including several of our more 
significant productivity enhancers. Your mileage will 
vary, of course, but we hope you find our set of tips 
as useful as we do. 



Case 1 : 



Case 2: 



Program Refs 




Object C 



Figure 1 Collect the Garbage. .NET objects are garbage-collected when they can no longer be reached from 
any executing code. In Case 1, Objects A and B are unreachable from the program, even though A maintains a 
reference to B. This means both will be garbage-collected. Object C is still reachable in Case 1, so it won't be 
garbage-collected until the reference to it goes out of scope. In Case 2, a circular reference exists between A, B, 
and C. In COM, these objects would never be destroyed because their reference counts would remain at 1 
each. In .NET, they will be garbage-collected because they are unreachable from the executing program code. 
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1. Avoid the Tilde (~) Finalizer 

Let's begin with a potentially confusing decision C#'s designers 
made: using the tilde (~) to denote a Finalizer. This can trip up C++ 
programmers, who naturally take this for a C++-style destructor, 
which has the same syntax but different functionality. Garbage 
collection is an article topic in itself, but you want to avoid using a 
tilde finalizer in .NET for several reasons. First, a finalizer is not 
deterministic, which means you have no guarantee when it will be 
called. Second, a finalizer carries additional overhead because the 
garbage collector must make at least two passes before it can collect 
objects with finalizers. Third, .NET's new garbage-collecting archi- 
tecture calls a finalizer on a different thread, which means the code 
inside a finalizer must be thread-safe. 

There's some good news, however. One major reason you need 
a destructor in C++ — releasing references to other objects — goes 
away in .NET. For example, assume object A maintains a reference 
to object B when no other entity holds a reference to A or B (see 
Figure 1). Both will get garbage-collected (even though A still holds 
a reference to B). This is because the garbage collector flags both as 
nonreachable. 

This also eliminates the circular reference bug, a common 
problem in COM development. Under .NET, if A holds a reference 
to B, which holds a reference to C, which holds a reference back to 

C# • Free Resources With the using Keyword 



using System. Drawing; 

class a 

( 

publ ic static void Main( ) 
f 

using (Font FontResourcel - new 
Fontt "Arial " . 10. Of), FontResource2 = new 
FontCArial". 10. Of)) 
( 

try 
1 

// use Font Resources 

I 

catch ( System. Exception e ) 
I 

return ; 

) // compiler will call Dispose on 
// FontResourcel and 
// FontResource2 
( // compiler will call Dispose on 
// FontResourcel and FontResource2 



Font FontResource3 = new Font( "Ari al " . 

using ( FontResource3) 

1 

// use FontResource3 
) // compiler will call Dispose on 
// FontResource3 



10. Of); 



1 



Listing 1 C#'s using keyword enables the compiler to determine 
automatically when the Dispose method needs to be called to free 
resources. In this example, the using statement ensures the Dis- 
pose method of the font objects is always called, regardless of how 
the function is exited. The instantiated objects must implement the 
System. IDisposable interface in order for the using statement to do 
its job correctly. 



A, and no reachable object holds a reference to any of these three 
objects, then A, B, and C will all be flagged as unreachable and 
eligible for garbage collection. In the COM world, which is based 
on reference counting instead of garbage collection, this situation 
results in the immortality of all three objects. 

2. Clean Up Resources With IDisposable 

You must still perform some cleanup when using .NET. Con- 
C# • Watch Out for Implicit Boxing 



using System . Drawi ng ; 
using System. Di agnosti cs ; 
class test 
t 

public static void MainO 

( 

i nt a = : 
int b - 0: 

ModifyTwoIntegers( ref a, ref b ); 

Debug. WriteLinet a.ToStringt) ); 

// will write out "5" 
Debug. WriteLinet b.ToStringO ); 

// will write out "10" 

a = 0; 
b = 0; 

// calling this method will cause an 
// implicit boxing operation making 
// copies of 'a' and 'b' which will 
// be discarded after the call 

ModifyTwo0bjects( a, b ); 

Debug. WriteLinet a.ToStringt) ); 

// wi 1 1 write out "0" 
Debug. WriteLinet b.ToStringO ); 

// wi 1 1 write out "0" 



public void ModifyTwoIntegerst ref int 
numberl, ref int number2 ) 

I 

numberl - 5; 
number2 - 10; 



public void Modify TwoObjectst object objectl, 

object object2 ) 

I 

objectl = 5; 
object2 = 10; 



I 



Listing 2 A boxing operation makes a copy of the value type and 
places that copy on the heap so it can be treated as a reference type. 
However, any changes made to the object inside the method aren't 
reflected back in the original value type object. For example, assume 
the values of a and b reflect the changes made after a call to 
Modify Twolntegers. Making a subsequent call to ModifyTwoObjects 
leaves the values of a and b unchanged because C# creates copies 
of the two integers through an implicit boxing operation and discards 
them after the call is made. 
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sider the case when an object holds some resources such as pens 
or database connections. In these cases, a destructor/finalizer is 
not appropriate because it's not deterministic. This means you 
could find yourself holding onto that resource for much longer 
than necessary. 

Therefore, you need a deterministic way to free these re- 
sources. The .NET Framework defines an interface called 
IDisposable that provides a solution. If the class you create needs 
to free these kinds of resources, you should implement the 
IDisposable interface in it. IDisposable has a single method, void 
Dispose(). Place the code to free up the resources inside this 
method. Typically, you do this by calling some referenced ob- 
jects' Dispose methods. All .NET Framework classes that require 
cleanup implement this interface, including the Pen, Brush, and 
Font classes. But be aware that someone still must call the Dispose 
method. People who use the class can do this explicitly or with the 
new C# using keyword. 



using System. Drawi ng ; 
using System. Diagnostics; 
class test 



( 



public static void MainO 
1 

Foo a = new Fool ) ; 

// call Bar thru the interface 
((IFoo)a).Bar(); 

// this will write out 'false' because the 

// above call performed a boxing 

// operation that created a 

// copy of the Foo struct, which was 

// discarded immediately after the call 

Debug. WriteLinet a .BarCal 1 ed .ToStringt ) ); 

// call Bar directly on the struct 
a. Bart ) ; 

// this will write out 'true' as expected 
Debug. WriteLine( a .BarCal 1 ed .ToStri ng( ) ); 



public interface I Foo 
( 

void BarO; 
) 

public struct Foo : IFoo 
( 

public bool BarCalled; 

public void BarO 
1 

this. BarCal led = true; 

) 
I 



) 



Listing 3 Calling the Bar method by casting the struct to the IFoo 
interface causes an implicit boxing of the struct. This creates a copy 
of the struct on the heap— a copy that is discarded immediately after 
the call. This is not only inefficient, but it means any state changes 
made inside the method call aren't reflected in the original struct. 



3. Handle Objects That Consume 
Resources With the using Keyword 

The C# language includes the using keyword, which enables re- 
sources to be freed automatically for specified objects, regardless of 
how or when the objects go out of scope (see Listing 1). 

The using keyword provides a cleaner, more efficient way of 
disposing resources than the traditional approach, where you must 
perform resource cleanup explicitly at each point of exit. You can 
ensure your applications don't leak resources by always adhering to 
the policy of working with the using keyword instead of calling the 
Dispose() method explicitly. 

4. Beware of Implicit Boxing 

.NET includes two types of objects: value types and reference types. 
Value types are classes derived from System. ValueType and include 
the intrinsic types such as int, bool, short, and so on. All other classes 
are reference types. The one exception to this rule is a struct, which 
is a value type. These types differ in where they are allocated and how 
they are referenced. You can create value types only on the stack 
(inside a method) or inline (as a member of a class or struct). You 
always create reference types on the heap, where the garbage 
collector manages them. 

This is a major departure from C++. Classes and structs in C++ 
are almost identical, and you can create any object (including 
intrinsic types) on the stack or on the heap. Also, the only way to get 
a reference to a value type in C# is as a parameter in a method marked 
"ref." If you pass a value type as a parameter into a method that 
expects a reference type parameter, the C# compiler performs an 
implicit boxing operation (see Listing 2). 

5. Don't Implement Interfaces on Structs 

C# allows structs to derive from one or more interfaces. This might 
sound like a nice capability, but it carries certain risks that can 
produce unwanted results. 

Structs are value types, so you can create them only on the stack 
or inline (as a member of a class). They are efficient because the 
garbage collector doesn't need to manage them. Unfortunately, this 
means the only way you can get a reference to a struct is by passing 
it as a ref argument into a method. 

You're faced with a question: How can structs implement inter- 
faces, which are, in effect, references? The answer: When you access 
the struct by casting it to an interface, an implicit boxing operation 
takes place and a copy of the struct is placed on the heap. You end up 
with a reference to the copy. When you call a method on the interface 
that changes the state of the object, you actually change the state of the 
copy, which gets discarded after the call (see Listing 3). 

If you have a struct that needs to implement an interface, 
consider using one of two approaches. The first: Declare it as a 
class instead of a struct. Declaring it as a class means the object is 
no longer creatable as an efficient stack object. On the other hand, 
you avoid implicit boxing when accessing the interface. The 
second approach: Keep your struct a struct, but create a wrapper 
class that contains the struct as a public member. Implement the 
interface off the class instead of the struct. You can then use the 
struct as a stack-based object or instantiate the wrapper class when 
the interface is required. You're actually performing the equiva- 
lent of a boxing operation, but it will be explicit rather than 
implicit, ensuring you won't do so accidentally. 
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6. Enable XML 
Documentation Generation 

Typing a triple slash (///) in the line before any 
element — whether a class, struct, interface, or any 
other element — prompts C#'s editor to generate a set 
(jf ftML I3jj5l YvU W p lage documentation for the 

element inside these generated XML tags. IntelliSense 
displays this documentation when you type in code 
that references the member. 

Getting the benefit of this IntelliSense documen- 
tation feature is complicated if the generated assembly 
is a class or control library that will be used in other 
assemblies. In this case, you need to create and distrib- 
ute an XML documentation file that contains these 
tags. You can do this as part of the C# project's build 
process, but you need to turn IntelliSense on using a 
four-step process. First, right-click on the project in 
the Solution Explorer pane and select Properties. This 
brings up a dialog; select Configuration Properties 
from the left-side tree. Next, make sure you select 
Build under Configuration Properties. Finally, the list 
on the right includes an item called XML Documen- 
tation File (see Figure 2). Specify the name of the 
XML file in this space. You must give this file the same name as the 
corresponding assembly, but with an XML extension. Otherwise, 
IntelliSense can't find the file. For example, assume the assembly is 
named Foo.Bar.dll; you must name the XML file Foo.Bar.xml. 

7. Reduce Memory Clutter 

Instances of the String class are immutable objects in C#. This means 
you cannot change a string object once you create it. It also means the 
system must create new string objects to incorporate changes any time 
you manipulate instances of string classes. For example, assume you 
need to compose several date components to yield a long date format: 

string Ful 1 DateTime; 

string DayOfWeek = "Tuesday"; 

st ri ng Month = "March " ; 

i nt DayOfMonth = 22; 

fnt Year = 2001; 



lnlr.itjistio.Win Property Pjgr* 
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Warning Level 


Warning level 4 




Treat Warnings As Errors 
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B Outputs 






Output Path 




H| Infragistics.Win.XML 




Generate Debugging Information 




Register for COM interop 


False 








XML Documentation File 

Specifies the name of a file into which documentation comments w3l be 
processed. Path must be relative to the project directory (/doc). 



Full DateTime - DayOfWeek + 
DayOf Month. ToString( )'.+ •" 



, " + Month + " " + 
+ Year .ToStri ng( ) ; 



In this case, you create a new string object each time the + operator 
is used to increment the length of the overall result. In the process, 
you create and throw away five strings before the final sixth string 
is allocated and assigned to the FullDateTime variable. 

Wasting a few string objects might not be significant in this 
example, but consider what happens when a method that performs 
extensive text manipulation does so by using the convenient addi- 
tion operator. For example, assume you have a Web application that 
generates a complex string of HTML to be sent down to a browser. 
There might be hundreds of statements that concatenate various 
strings before writing them to an HttpTexrWriter object. Each time 
the HTML string is extended, the app creates a new string to hold 
the longer string, and the old string is thrown onto the garbage heap. 
Over an extended period of time, such activity gradually depletes 



Figure 2 Specify the XML Documentation File. This dialog lets you specify the 
name of the XML file to be generated during the build process of a C# project. Note 
that you set the Configuration dropdown to All Configurations, which causes the 
XML documentation file to be generated during both debug and release builds. 



memory and degrades performance on a server where the page is 
requested frequently. Eventually, garbage collection will run and 
clear up the old, unused strings — but there is a better way. 

You can use the StringBuilder class to build up and extend strings 
that consist of smaller, incremental units: 

StringBuilder buffer = new Stri ngBui 1 der( ) ; 

buffer. Append(DayOfWeek) ; 

buf fer . Append (" . "); 

buffer. Append(Month); 

buffer. Appendt " "); 

buf fer. Append (DayOfMonth .ToStri ng( ) ) ; 

buffer. Appendt " "); 

buf fer. Append ( Yea r.ToStringt ) ) ; 

The StringBuilder class utilizes a single buffer, which is capable of 
expanding to whatever size is required. This second example re- 
quires writing a bit more code, but it doesn't change the size or 
performance of the compiled IL. Using the StringBuilder class 
instead of performing string concatenations saves you considerable 
memory usage and helps you avoid fragmentation. 

8. Use is and as Keywords 
for Type Checking 

Strong type checking is a basic aspect of the .NET Common 
Language Runtime, so sometimes you must verify the type of an 
object in an application before calling one of its methods or 
properties. Failure to do this leads to an unhandled exception, and 
the program will terminate if you attempt to access an object as a 
type other than what it is. This situation can occur when an 
ambiguous object is passed to a method and the method must 
determine the object type prior to using it. You can do this in several 
ways in C#. 

For example, assume you need a method that determines the 
type of object passed as a parameter and only processes the object if 
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it's of type string or of type int. You can use exception handling to 
check an object's type in this circumstance (see Listing 4). 

The exception-handling approach works as expected, but it's 
somewhat clumsy and awkward to use. An effective alternative: 
Take advantage of C#'s is keyword to accomplish the same goal with 
considerably less code and more readability. This code produces the 
same output as the first example: 

public int footobject o) 
1 

if(o is string) 

return processStringObject(o) : 
el se 

i f (o is i nt ) 



class Classl I 

static void Main(string[] args) I 
int result; 

ProcessObjects process = new ProcessObjectst ) ; 
result = process .fooChel lo" ) ; 

Console. WriteLineCThe first call returns 101". result): 
result - process. foo(10) ; 

Console. WriteLineCThe second call returns 101". result): 
result = process. foo(35. 3); 

Console. WriteLineCThe third call returns 101". result); 

1 

1 

class ProcessObjects 
{ 

public int footobject o) I 
try { 

string s - (string)o; 

return processStringObject(s) ; 

1 

catch ( System. Inval idCastException ) f 
try ( 

int i = (int)o; 

return processIntObjectt i ) : 

1 

catch ( System. Inval idCastException )( 
return -1; 

} 

) 

1 

public int processStringObjecttstring s) I 
return s. Length; 

I 

public int processIntObjecttint i) 



return i .ToStringt ). Length; 



) 



// The output from this sample: 

// The first call returns 5 

// The second call returns 2 

// The third call returns -1 



Listing 4 You can use exception handling to determine the type of 
an object. Simply "try" different objects to see if you have a match. 
If the object type cast fails, an exception is thrown, and you try an- 
other type of object in the catch block. 



return processIntObject(o) ; 
el se 

return -1; 



You have yet another option available to you. You can use the as 
keyword to make the object assignment, assigning a null value if the 
object is not a compatible type. One limitation of the as keyword: 
It can be applied only to variables that are object references; it can't 
be applied to value types. This is because you cannot assign value 
types a null value, which is crucial if you want to test the result of the 
object conversion. 

So, this code uses the as keyword in the test for the string type 
(a reference type), but it uses the is keyword to test for the int type 
(a value type): 



public int footobject o) I 
string s = o as stri ng : 
ifts != null ) 

return processStri ngObject ( s ) ; 
el se 

if to is int) 

return processIntObject ( ( i nt )o) ; 

el se 

return -1; 

I 

This version of foo also produces the same output as the first example. 

This demonstrates that you can often use C#'s is and as keywords 
interchangeably. Both keywords can be useful, and both are much 
more readable and understandable than the use of exception han- 
dling in these situations. «M 
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Manage C# Objects 



.NET has a garbage collector, but managing objects takes more than 
conserving memory. Here's how to manage object lifetimes effectively. 



by Bill Wagner 



Technology Toolbox 

□ VB.NET 

Kf C# 

□ SQL Server 2000 

□ ASP .NET 

□ XML 

□ VB6 
Sf Other: 

Visual Studio .NET 
beta 2 or later 



# programs run in a managed environment, and 
that environment manages memory resources 
for you. Even with such memory-management fea- 
tures, however, you still need to address program- 
ming issues that encompass your objects' lifetimes. 
You need to consider how long objects live and how 
the runtime environment destroys these objects. You 
might also need to manage more closely the resources 
objects acquire on your behalf. Even using pointers in 
unsafe code has ramifications for the garbage collec- 
tor. In this article, I'll show you how to work with the 
runtime's garbage collector when you use .NET 
classes and how to write classes that work efficiently 
in the managed environment (see the sidebar, "Ob- 
ject Management Guidelines"). 

Along the way, I'll add animation to an applica- 
tion that displays the Mandelbrot set, a collection of 
complex numbers that creates fractal patterns when 
graphed. In tuning the application for performance, 
you'll learn more about how to use C# to work with 
the memory resources in the Common Language 
Runtime (CLR). 

Essentially, the garbage collector frees and com- 
pacts memory by removing unnecessary objects, free- 
ing you from dealing with the memory used by 
objects you allocate. However, you can structure your 
code to take better advantage of the garbage collector 
and increase performance. 



Resources 



• A Programmer's Introduction to C#by Eric Gunnerson [Apress, 2001, 
ISBN: 1893115623] 

• Inside C/by Tom Archer [Microsoft Press, 2001, ISBN: 0735612889] 

• Chaos: Making a New Science by James Gleick [Penguin, 1988 (reprint 
edition), ISBN: 0140092501] 

• "Garbage Collection: Automatic Memory Management in the Microsoft 
.NET Framework" by Jeffrey Richter [MSDN]: http://msdn.microsoft.com/ 
msdnmag/issues/1100/gci/gci.asp 

• "Garbage Collection — Part 2: Automatic Memory Management in the 
Microsoft .NET Framework" by Jeffrey Richter [MSDN\: http:// 
msdn.microsoft.com/msdnmag/issues/1200/gci2/gci2.asp 

• Visual Studio .NET home page: http://msdn.microsoft.com/vstudio/ 
nextgen/default.asp 



The .NET Runtime Garbage Collector uses a 
"Mark and Compact" algorithm that, instead of 
searching for dormant objects, finds and marks ob- 
jects still in use. Any objects not marked as "in use" are 
freed, and the heap is compacted. Live objects move 
in memory when the garbage collector runs. The 
garbage collector runs only when necessary, such as 
when an allocation fails. The more objects you allo- 
cate, the more often it runs. 

The garbage collector makes some assumptions 
about the likelihood of objects being unused: If an 
object survives garbage collection, it will likely survive 
future garbage collections. The idea is that local 
variables do not survive their first garbage collection. 
Any variable that does survive its first garbage collec- 
tor operation is probably owned by an application- 
level object and therefore likely to be around for a 
while. If an object survives two or more garbage 
collector operations, the application probably owns 
it, so will likely be around for a long time. 

The garbage collector first examines the zero- 
generation objects — objects that have never been 
examined. Ifthe application needs more free memory, 
the garbage collector examines the first-generation 
objects and, if necessary, the second-generation ob- 
jects. The goal is to free enough memory from the 
garbage collector operation with minimal work. 

Your mission is to avoid creating extra objects 
needlessly and avoid calling the garbage collector too 
frequently. The garbage collector is efficient, how- 
ever, and you want to work with it, not against it. You 
don't need to avoid creating objects for fear of garbage 
collection, but you do need to avoid being wasteful; 
if you can reuse an object as easily as creating a new 
one, do so. 

For example, consider the differences between the 
String and StringBuilder classes. Examine this code 
from my Mandelbrot application: 

String msg = "This shows the \ 

Mandelbrot Set from the Range:"; 
msg += "\nx=( "+minX.ToString () 

+" , "+maxX.ToString ()+")"; 
msg += "\ny=( "+minY .ToStri ng( ) 

+"."+maxY.ToString ()+")"; 
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msg += "\nEach Pixel represents { "+ 
seal eX .ToStri ng ()+","+ 
scaleY.ToString ()+")"; 

String is a different animal. Each time the msg string is assigned 
a new value, a new string is created. You can write this more 
efficiently using the StringBuilder class: 

StringBuilder msg - new Stn'ngBui Ider 

("This shows the Mandelbrot Set \ 

from the Range : " ) ; 
msg .AppendFormat ( "\nx={ 0:e4 I . 

U:e4) )\ny=( (2:e41 . (3:e4))", 

minX. maxX. minY. maxY): 
msg .AppendFormat ("\nEach Pixel \ 

represents ( ( 0: e4 I . 1 1 : e4 1 ) " . 

scaleX, scaleY); 
System. Wi n Forms .MessageBox. Show 

(msg. ToStri ng( ) ) ; 

Only one String is built in the second example, located in the 
msg.ToStringO call that displays the message. In the first example, 
19 different String objects are created — one for each string literal, 
one for each ToStringO call, and one each time the variable msg is 
assigned. So 19 different objects are orphaned after this code 
executes. Although each object is small, you can see how this can add 
up over time. 

Dispose of Objects 

How do you free nonmemory resources? Well, you must do it 
yourself. Any object owning resources that must be freed must 
implement the IDisposable interface. After finishing with the 
object, you call Dispose() on the object, which frees any resources 
it has acquired (such as file handles, locks, cursors, and open 
database tables). 

Whenever you use objects, determine whether they implement 
the IDisposable interface. If so, call the Dispose() method when you 
finish using the object. This is the most efficient way to free 
nonmemory resources. If you forget to call Dispose(), however, the 
FinalizeO method found in most objects takes care of resources. (I'll 
explain more about how FinalizeO affects performance later.) 

If you create a class that acquires resources that must be freed, you 
should implement the IDisposable interface for that class so clients 
can call the Dispose() method to release resources. To implement the 
interface, declare that your class supports the IDisposable interface 
and implement the DisposeO method. 

DisposeO and Finalize()work together often. Suppose you have 
a class that needs a handle to some resource. This code shows how 
the DisposeO method would work: 

class myClass : IDisposable 
I 

private Handle hnd; 

myClass () 

I 

hnd = new Handl e ( ) : 
hnd. Acquire (); 



public void Dispose ( ) 
I 

hnd. Release (); 
hnd - null; 

GC.SuppressFinalization 

(this): 




Figure 1 Animate the Set. Although you can't see it on paper, 
this window is cycling through all the colors in the set in real time. 
You can see the interesting effects for yourself by downloading 

the code. 



Object Management Guidelines 

Follow these guidelines for working with the Common Lan- 
guage Runtime (CLR): 

1 . Let the garbage collector do its work. Avoid using FinalizeO or 
DisposeO to release memory resources. 

2. FinalizeO slows down the garbage collector. If you implement 
FinalizeO, you should also implement DisposeO so you can 
clean up the object more effectively. 

3. Use the GC.SuppressFinalization!) method to remove dis- 
posed objects from the finalization list. 

4. Make sure the DisposeO and FinalizeO methods can be called 
in any order and more than once. 

5. Test for an already disposed object in public methods, at least 
in debug builds. 

6. Use the IDisposeO interface if an object supports it. If possible, 
use the "using" statement to ensure exception-safe code. 

7. Use weak references for large objects that might be needed 
later. This technique can improve performance greatly, but 
you should use it sparingly — only when you're working with 
large, resource-intensive objects. Using it too often takes 
more cycles to resurrect objects. 

8. If you use unsafe code to boost performance, make sure you 
don't keep unbaie pointer s around long because trrey prevent 
the garbage collector from doing all its work. You need to 
check unsafe code carefully and use it only when you have 
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protected void Finalize () 

I 

hnd. Release (); 



Notice that I call GC.SupptessFinalization 
(this) to remove the object from the finaliza- 
tion queue (I'll describe this later when I 
delve into finalization). You can also access 
an object that has been disposed. Using 
other methods, you would need to check 
that hnd isn't null and reacquire the object 
if necessary (this is why the hnd variable is 
set to null in the Dispose() method). 

You don't need the IDisposable interface 
for memory resources — in fact, you shouldn 't 
use it. Instead, use the DisposeO method to 
free other system resources, such as files, data- 
base tables, or other resources. 

Exceptions and 
Resources 

The techniques I've covered so far are pretty 
simple. When you finish using an object, the 
garbage collector handles the memory re- 



sources for you. If the class supports the 
IDisposable interface, you call the DisposeO 
method when you're done with the object. 
But what happens when exceptions occur? 
Because DisposeO is not called automatically 
duting the stack unwinding process, you 
need to structure your code so you call Dis- 
poseO if your function exits normally, or if an 
exception is thrown through your functions. 

You don't 
have to 
implement a 
finalizer when 
you use the 
DisposeO 
method. 



You can do this in one of two ways. 

First, you could add your own try and 
finally blocks to ensure DisposeO gets called. 
Suppose myClass is a class that implements 
the IDisposable interface. You could write 
this code: 

myClass obj = new myClass (); 
try ( 

obj. Function (); 

I 

final ly 
I 

if (null !- obj) 

( ( IDisposablelobj ) .Di spose (); 



C#'s using statement, however, gives you a 
much easier way. The statement indicates 
that you're using a variable inside a block 
and that the object should be disposed of 
when the block exits. You can replace the 
previous example with this code: 

using (C obj = new C ( ) ) 
I 

obj. Function (); 
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The DisposeO method is called at the close of the using block, 
whethet ot not any exceptions are thrown. 

In C#, destructors are declared just like C++ destructors: with a "-" 
preceding the class name. This is syntactically equivalent to declaring 
a Finalize() method. In fact, the C# compiler replaces destructor calls 
with calls to the Finalize() method. You can use this code: 



class myClass 
I 

publ i c myCl ass ( ) 
I 

// Do stuff. 

I 

-myClass () 
I 

// Free stuff. 

1 

1 

or this code: 

class myClass 
I 

public myClass ( ) 
I 

// Do stuff. 

1 

protected override void FinalizeO 
I 

// Free stuff, 
base . Fi rial i ze (): 

1 

I 

Whichever you use is a matter of style; I would expect C++ 
programmers to use the destructor syntax, while those with Visual 
Basic and Java backgrounds might be partial to the FinalizeO syntax. 
Remember: The FinalizeO method is not called when an object goes 
out of scope, as it is in C++. Instead, it is called as part of the garbage 
collector operation. For that reason, I prefer the FinalizeO syntax to 
the destructor syntax; it looks different because it is different. Final- 
ization has performance implications as well. Let's revisit the discus- 
sion of die CLR garbage collector from the beginning of this article 
and look at what happens when objects to be released have finalizers. 

The runtime keeps track of objects that require finalization. 
When the garbage collector runs, it moves any objects that could be 
collected but require finalization to a "ready for finalization" list. 
After garbage collection, the finalizer thread wakes up and calls the 
FinalizeO method on the objects on the finalizer list. The objects are 
removed from the finalization list and are now ready for the next 
round of garbage collection. Objects that require finalizers slow 
down the system and live longer than necessary when garbage 
collections occur. 

To improve this situation, implement the FinalizeO method, the 
IDispose interface, and the DisposeO method. In your DisposeO 
method, call GC.SupressFinalization (this), which removes the 
object from the finalization queue. Now the object can be garbage- 




Figure 2 Using the Unsafe Pointers Incorrectly. If you forget 
which index in the 2-D matrix is the major axis, you get some 
unsatisfactory results. You can see the effects by downloading 
the code and switching the xand / indexes in the matrix storing 
the Mandelbrot set values. 



collected without waiting for the finalization thread to execute. 
Notice that you don't have to implement a finalizer when you use 
the DisposeO method. 

Let's add the animation code to the Mandelbrot set application. 
The design is pretty simple: You add a timer to the application, then 
you add an event handler to cycle through the colors (download 
Listing 1). The mandel object calculates an integer value for each 
(x,y) point in the Mandelbrot set. The colormap is a class in the 
project that transforms a grayscale value into a color value to create 
color images. (Download the code for the entire example to see the 
finished version; see the Go Online box for details.) The DisposeO 
method in Listing 1 lets the other components release their re- 
sources. The new version of the application object does not need to 
have a FinalizeO method; the timer's own FinalizeO frees any 
resources if for some reason DisposeO is not called. 

Use Weak References 

Now I'll address performance issues in the Mandelbrot application 
because the first version of the animation code is way too slow. One 
way to boost its speed is to avoid recalculating the Mandelbrot set 
points every time the colors change when the set gets animated: You 
add a class (download Listing 2) that holds the number of iterations 
in the Mandelbrot set. The class simply stores a matrix of integers; the 
matrix is the same size as the display. Now, when the set is animated, 
you need to change only the pixels. You don't need to recalculate the 
set points each time the display changes, saving more than 30 1 ,000 
calculations. However, the application now uses much more memory, 
even when you're not animating the set. You can save this cost by 
replacing strong references with weak references. 

A weak reference is a reference to an object that can be garbage- 
collected — essentially, it lets you set aside an object in case the system 
needs to collect it. If you don't access that object before a garbage 
collection occurs, the garbage collector removes it from memory. If 
you do access the object before a garbage collection, the object is 
returned. Saving the Mandelbrot matrix as a weak reference keeps the 
cached results in memory if memory is not becoming scarce (down- 
load Listing 3). The advantage is that you do not need to re-create the 
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image to animate it. In addition, if memory becomes scarce and the 
system needs to perform a garbage collection, you don't need to do any 
extra work — the system frees the reference for you. 

The application performed better with the weak reference, but 
it's still not fast enough. To improve the speed further, I used unsafe 
code and pointers. I added the DisplayO method to the PelMap class 
(download Listing 4) . This routine grabs a pointer to the start of the 
matrix of integers and a pointer to the start of the bitmap image. 
Then I use pointer arithmetic to move through both blocks of 
memory. The unsafe keyword marks the block as not running inside 
the managed environment. The two fixed blocks specify pointers to 
raw memory. The fixed keyword notifies the runtime that the object 
being pointed to cannot move in memory. Without the fixed 
blocks, the runtime can move the object in memory as part of a 
garbage collection action, which is one of the main reasons for the 
performance improvement. 

With managed references, you must resolve each access indepen- 
dently because the object might have moved between instructions. 
Also notice that I reversed the x and y indexes in the cache. The first 
index in the matrix is incremented last, and that must be the y index. 
The Turnerizer transforms the integer values into color values for 
display. Now the animation routine runs in real time. Download the 
code and try it yourself. You can even zoom into different areas of 
the set while it's animated. Try switching the x and y indexes in the 
cache to get some visually interesting effects (see Figures 1 and 2). 

I've shown you how to work with the garbage collector to 



improve your application's performance. Most of the time, you'll be 
better off letting the garbage collector do its thing without any 
particular guidance. When you write code that has some unique 
memory usage characteristics, however, you can use the techniques 
I've described to modify the default behavior, vsm 



Bill Wagner is a founder and software consultant for SRT Solutions, 
and he has more than 1 5 years of software development experience. 
He has been a columnist for Visual C++ Developers Journal and has 
written two eBooks on STL programming, available at www. 
mightywords.com. Contact Bill atwwagner@srtsolutions.com. 
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As you begin traveling down the Windows* 
Installer highway, make sure you have the 
power you need to reach your destination. 

Other installation tools may get you started using Windows 
Installer technology, but only one has the power you need, 
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As you well know from traditional component- 
oriented programming, separating the inter- 
face from its implementation provides polymorphism 
between different implementations of the same ser- 
vice. The separation recognizes the fact that the basic 
unit of reuse in any application is the interface, not 
the object implementing it. You can apply this core 
principle of component-oriented pro- 
gramming to Web Service develop- 
ment as well. 

In this case, the interface is a logical 
grouping of method signatures that act 
as the contract between the client and 
the Web Service provider. You can 
then switch between different provid- 
ers with minimal or no changes to the 
client code because the client is written 
against an abstract service definition 
(the interface) rather than a particular 
service implementation. 

The Web Services standard sup- 
porrs interfaces (referring to them as 
ports). But by default, Web Services 
support in .NET is method-based, not 
interface-based. So VS.NET, as it ex- 
ists today, doesn't inherently allowyou 
to develop interface-based Web Ser- 
vices. I'll show you the simple steps 
required — both on the server and cli- 



by Juval Lowy 

ent — to compensate for the lack of interface-based 
Web Services in VS.NET, allowing you to develop 
and consume interface-based Web Services. But first 
I'll set up an example scenario. 

Suppose you have a Web Service called Simple- 
Calculator that provides the four basic arithmetic 
operations — addition, subtraction, division, and 




Figure 1 Expose an Interface Definition. To expose a Web 
Service interface definition, add a new Web Service item and 
give it an interface name. Clicking on the Open button causes 
VS.NET to create a skeletal Web Service. From there, remove all 
the implementation code from the wizard-generated code. 
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multiplication — and a client that consumes 
the Web Service. You implement the Simple- 
Calculator Web Service in .NET using C# (see 
Listing 1). 

Simply add the [WebMethod] attribute 
to the methods you want to expose as Web 
Services — Add(), Subtract(), Divide(), and 
MultiplyO — and .NET does the rest. Note 
that having WebService as a base class is 
optional; deriving from it gives you easy ac- 
cess to common ASP .NET objects, such as 
those for application and session states. You 
don't need these objects in this use-case. Also 
optional is the WebService attribute, but I 
strongly recommend you use it. 

The WebService attribute lets you specify a 
Web namespace that contains your service, 
which you can use as you would a normal 
.NET namespace to reduce name collusion. If 
you don't specify a namespace, VS.NET uses 
http://tempuri.org/ as a default. A published 
service usually uses a specific Uniform Re- 
source Identifier (URI) as its namespace, typi- 
cally the service provider company's name. 
The WebService attribute also allows you to 
provide a free-text description of your service 
that appears in the auto-generated browser 
page used by Web Service consumers and 
during development. 

Writing the client code is almost equally 
trivial. Select Add Web Reference. . . from the 
client's project in VS.NET and point the wiz- 
ard at the site containing the Web Service 
ASPX file. This makes VS.NET generate a 
wrapper class — called SimpleCalculator — that 
the client will use (see Listing 2). The Simple- 
Calculator wrapper class has all the methods 
the Web Service developer applied [Web- 
Method] to as public methods. The wrapper 
class (sometimes called a "Web Service Proxy" 
class) encapsulates completely the complex 
interaction with the remote object. The wrap- 
per class is also the only entity coupled to the 
service's location — its base class, SoapHttp- 
ClientProtocol, has a property called Url that 
points to the object's location. 

The client code uses the wrapper class as 
if the SimpleCalculator object were a local 
object: 

SimpleCalculator calculator: 
calculator - new SimpleCalculator( ) : 
int result = cal cul ator . Add(2 ,3 ) ; 
Debug. Assertt resul t = 5); 



Clearly, VS.NET makes invoking Web methods trivial. 

But you have a problem: The client ends up programming 
directly against the "object" providing the service (SimpleCalculator 



C# • It All Adds Up With the SimpleCalculator Class 



[WebServi ce( 
Namespace= 

"http: / /Cal culationServices .com" , 

Description - "The SimpleCalculator Web Service provides the four 
basic arithmetic operations for integers.")] 
public class SimpleCalculator: WebService 
I 

public SimpleCal cul ator( ) I ) 
[WebMethod] 

public int AddCint numl, int num2) 



return numl + num2; 



[WebMethod] 

public int Subtracttint numl, int num2) 



num2 ; 



[WebMethod] 

public int Dividetint numl, int num2) 

I 

return numl / num2; 

I 

[WebMethod] 

public int Multiply(int numl, int num2) 

I 

return numl * num2: 



Listing 1 To expose a class method as a Web Service, simply add the IWebMethod] 
attribute. Note that deriving from WebService is optional. Using the [WebService] 
attribute is optional also, but you should use it to provide a service description and 

containing namespace. 



C# • Encapsulate the Interaction 



public class SimpleCalculator : SoapHttpCl i entProtocol 

( 

public Simpl eCal cul atort ) 
I 

Url = "http://www.CalculationServices.com/SimpleCalculator.asmx" 



[SoapDocumentMethod( "http: //Cal cul at ionServi ces .com/Add" ) ] 
public int Addtint numl, int num2) 
I 

object[] results = InvokeCAdd" . new object[] I numl ,num2 ) ) ; 

return ( int )( resul ts[0] ) ; 

I 

// Other method wrappers 



Listing 2 The SimpleCalculator Web Service wrapper class — generated for the Web 
Service shown in Listing 1 — encapsulates the interaction with the Web Service 
completely and shields the client from the details. It contains the service location in 
the public Url property, which is defined in the SoapHttpClientProtocol base class. 



in this case) instead of against a generic abstraction of such a service. 
You want the SimpleCalculator Web Service polymorphic with a 
service abstraction — an interface. 

For example, imagine the client wants to switch from the 
SimpleCalculator to a different calculator Web Service, called 
ScientificCalcuIator. ScientificCalculator supports the same inter- 
face as SimpleCalculator, but it's perhaps faster, cheaper, or more 
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accurate. You'd like to define a generic calculator 
interface, the ICalculator interface, and expose it as 
Web Service: 

// Imaginary attribute. 
// Does not exist in .NET 
[Weblnterface] 
interface ICalculator 
I 

int AddO'nt numl.int num2); 
int Subtracttint numl.int num2); 
int Dividetint numl.int num2); 
int Multiplytint numl.int num2); 

1 



C# • Prepare for a Service Provider Change 



// Somewhere in the client code, it 
// decides on the service provider: 

ICalculator calculator = (ICalculator) new Scienti f i cCal cul atort : 

// or 

ICalculator calculator = (ICalculator) new Simpl eCal cul atort ) ; 

// This part of the client code is 

// polymorphic with any provider of the service: 

int result = cal cul ator . Add( 2 . 3) ; 

Debug. Assertt resul t — 5); 



Assuming you could do that (I'll show you how 
shortly), you can code against only the interface 
definition instead of a particular implementation of 
it (see Listing 3). 

The only thing that changes in the client's code when it switches 
between service providers is the line that decides the exact interface 
implementation to use. You can even put that decision in a different 
assembly than the "main" client's logic, and you can only pass 
interfaces between the two. Another benefit you can reap from 
interface-based Web Services: The client can publish the interface 
definition, enabling different service vendors to implement the 
client's requirements more easily. 

Now you're ready to write the server and client code to work 
around VS.NET's lack of support for interface-based Web Services. 

Define and Implement a Web Interface 

To enable an interface-based Web Service, first expose the Web 
Service interface definition. For simplicity's sake, assume the 
service provider is responsible for both defining and implement- 
ing the interface (the client or any third party can expose the 
interface definition and have anybody implement it, but it re- 
quires additional steps). 

Create a new Web Service project called CalculationServices. 
Right-click on the project and select Add Web Service. ... In the 
Add New Item dialog, type "ICalculator" as the interface name and 
click on Open (see Figure 1). 

VS.NET then creates a skeletal Web Service called ICalculator. 
Open the ICalculator.asmx.es file and change the ICalculator type 
definition from "class" to "interface." Remove the derivation from 
System.Web. Services. WebService, as well. An interface, by defini- 
tion, has no implementation code — remove the constructor and the 
InitializeComponentO and Dispose() methods. Finally, remove the 
commented HelloWorld() method example. 

Next, add the interface methods — Add(), Subtract(), Divide(), 
and Multiply(). Although in principle you could simply apply the 
[WebMethod] attribute to each interface method to expose the 
interface as a Web Service definition, you shouldn't in practice 
because of the [WebService] attribute. This attribute applies only to 
classes, and it's sealed — you can't subclass it or change it. So you can't 
assign a namespace and a description to the interface, which I advised 
you to do earlier. To clear this hurdle, you must provide an interface 
"shim" — an abstract class that exposes what looks like a pure interface 



Listing 3 Ideally, you want your calculator Web Services polymorphic with a 
service abstraction — an interface. You can then switch between service providers 
with minimal or no changes to the client code. 



Vs.A/ET, as it 

exists today, 
doesn't inherently 
allow you to 
develop interface- 
based Web 
Services. 



definition. In the ICalculator.asmx.es file, add the ICalculatorShim 
pure abstract class definition: 

[WebServicet 

Name = "ICalculator" , Namespace= 
" http : //Cal cul ationServ ices. com". 

Description = "This Web Service is only the definition of 
the interface. You cannot invoke method calls on it.")] 
abstract class ICalculatorShim : ICalculator 
1 

abstract public int 
Addtint numl.int num2); 



abstract public int 
Subtracttint numl.int num2); 

abstract public int 
Dividetint numl.int num2); 

abstract public int 
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MultiplyCint numl.int num2); 
1 

Note that because ICalculatorShim is a class, you can use the 
[WebService] attribute to provide a namespace and description. In 
addition, you set the Name property of the [WebService] attribute 

to ICalculator to expose the service definition as ICalculator instead 

of ICalculatorShim. 

You're interested in exposing only the signatures, so you 
don't need the implementation code. Because you're using an 
abstract class and abstract methods, VS.NET insists that the 
ICalculatorShim Web Service have no implementation code — 
only a service definition. 

To verify that all is well so far, set the ICalculator.asmx file as the 
start page and run the project; the auto-generated browser page 
presents the ICalculator interface definition. If you try to invoke any 
of the methods, you should get an error because there's no imple- 
mentation behind the service. 

Next, implement the ICalculator interface on a Web Service 
class. This is like implementing any other interface in .NET — your 
Web Service class should inherit from the interface and provide the 
implementation for its methods. In this example, provide two class 
implementations: the SimpleCalculator and the ScientificCalculator 
Web Services (download Listing 4 from the VSMWeb site; see the 
Go Online box for details). 



Use the Add Web Service... context-menu item again to add 
the two Web Services. Add a derivation (inheritance) from the 
ICalculator interface (you can remove the derivation from the 
WebService base class — it bears no relevance to interface-based 
Web Services). Add the implementation to the Add(), Subtract(), 
Divide(), and MultiplyO interface methods. You must provide the 
[WebMethod] attributes for the interface methods you want to 

expose as Web Services. Without [WebMethod] on a class imple- 
mentation method, .NET won't expose the method as part of the 
Web Service. 

Write the Client-Side Code 

The client needs to add a reference to the type definitions of the 
interface and the classes implementing it. You can add the interface 
reference in one of two ways. The first uses the WSDL.exe com- 
mand-line utility. Using the /server switch, you can instruct 
WSDL.exe to generate a pure abstract class matching the Web 
Service definition. Assuming the interface definition resides at 
http://www.CalculationServices.com/ICalculator.asmx, run the 
utiliry with this command line: 

WSDL.exe /server /out: ICalculatorDef.es 

http: //www. Cal cul ationServi ces . com/ICal cul a tor . asmx 

Then add the ICalculatorDef.es source file to the client project. 
Unfortunately, even though .NET knows about interfaces, the 
/server switch generates a pure abstract class with abstract methods: 

public abstract class ICalculator : WebService 
I 

[WebMethod] 

[SoapDocumentMethodAttri buteC'http:// 
Cal cul ationServi ces. com/ Add" ] 

public abstract int Addtint numl. int num2); 
// rest of the ICalculator methods 

I 

But what you need is an interface definition. Open the 
ICalculatorDef.es file, remove the WebService base class, and 
change the ICalculator definition from abstract class to interface. 
Remove all the attributes (on ICalculator and its methods) and the 
public and abstract modifiers from all the methods. You should 
now have the original interface definition. 

The second way a client can import the interface definition: Add 
a Web reference to the ICalculator Web Service, then extract the 
interface methods from the wrapper class. To do so, point the Add 
Web Reference. . . wizard to the site containing the interface defini- 
tion. This generates a wrapper class called ICalculator, which 
exposes the original ICalculator's methods as well as a Web Service 
wrapper class's other methods. You need only method definitions 
for an interface, so remove all the interface method bodies and the 
other methods completely, including the constructor. Remove the 
SoapClientProtocol base class and the "public" modifier on the 
interface method. Remove all class and method attributes. Lastly, 
change the ICalculator definition from "class" ro "interface." Essen- 
tially, the client should now have the original interface definition. 

Next, the client must add a Web reference to the Web Services 
that provide the interface's implementation. Again, using the Add 
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Web Reference. . . wizard, point the wizard to where those imple- 
mentations reside. VS.NET generates wrapper classes for those 
implementations — SimpleCalculator and ScientificCalculator, in 
this example. These machine-generated wrapper classes won't 
mention ICalculator. To provide polymorphism with ICalculator, 
add a derivation from it. The SimpleCalculator and Scientific- 
Calculator classes should now look like those in Listing 5, which 
you can download. 

Here's the client-side design pattern: ICalculator provides the 

service definition. The Web Service's loca- 

tion is decided at the derived SimpleCal- 
culator or ScientificCalculator classes. The 
wrapper classes know how to forward the 
calls to the Web Service, but not how it's 
implemented on the server side. In fact, all 
that distinguishes SimpleCalculator from 
ScientificCalculator is the encapsulated ser- 
vice location or provider. 

Finally, you can now write interface- 
based, polymorphic Web Services code (see 
Listing 3). You can also make an interesting 
observation: From the client's perspective in 
the Web Services world, the location of the 
service — the URL — is the object. 

Web Services will become part of almost 
every developer's career in the next few 
years. However, the supporting tools are 
immature compared to existing design meth- 
odologies and component-oriented tech- 
nologies you've grown accustomed to in the 
intranet world. Today's challenge is how to 
combine the two. I hope this article con- 
vinces you not to give up on proven and 
elegant concepts just because VS.NET 
doesn't support them. With a bit of tweak- 
ing and the proper observation that a URL 
equals an object, you can employ estab- 
lished concepts in a brave new world, vsm 
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Build a Project 
Documenter Utility 



Explore the VBDoc project to learn debugger tricks and shortcuts on your way to 
building a utility that documents yourVB projects. 



by Stan Schultes 



□ VB.NET 

□ C# 

□ SQL Server 2000 

□ ASP .NET 

□ XML 
GTVB6 



I f I can say one thing about myself, it's that I'm lazy. 

I I spend all kinds of time writing comments in my 
programs, but I hate spending time creating docu- 
mentation describing the apps I've written. I do like 
to write code, however, so I decided to write a utility 
to help automate my documentation chores. This 
month's VBDoc utility extracts and formats com- 
ments in your VB6 projects to use as a starting point 
for your project documentation. Download the sample 
code from the VSM Web site and follow along (see the 
Go Online box for details). 

Load and run VBDoc in the VB design environ- 
ment to see how it works. The default project is 
VBDoc.vbp itself, or you can click on the Browse 
button to choose a different VB project. You can see 
a list of the project's files in the Files in Project listbox. 
Click on each filename in turn to see the header 
comments displayed in the Contents area. Header 
comments include the first contiguous block of com- 
ments in the file. If the file includes optional delim- 
iters ('+= and '-= by default), the header comments 
include the delimiters and all lines in between. You set 
the desired delimiters with the Tools | Set Delimiters 
menu item. You can edit and save the header com- 
ments in the Contents area without modifying the 
source files. 

Click on the Show Docs button to fill the contents 
area with formatted text. Because the Contents area is 
a RichTextBox control, VBDoc can use font styles to 
delimit sections in the documentation output. Project 
attributes are listed first, followed by the header com- 



ments for each file in your project. You click on the 
Save Docs button to save the documentation to a Rich 
Text Format (RTF) file you can edit with Word or 
other applications (see Figure 1). The file defaults to 
the project name and directory, as in VBDoc.rtf. 

Set breakpoints at important points in the VBDoc 
project so you can see how the code operates. Go to 
the Project Explorer (View | Project Explorer or 
Ctrl+R) in the VB design environment. Right-click 
on frmMain and choose View Code from the context 
menu, or click on the View Code icon at the top of the 
project window. Set a breakpoint on the first line in 
frmMain's CreateDocFile routine by clicking in the 
gray-colored left matgin next to the line containing 
the GetPath call. VB highlights the line of code in red 
when you set a breakpoint. You also set breakpoints 
on the first executable lines in the ShowFileDoc and 
ShowDoc routines, as well as on the first executable 
lines in clsProject's ProjectFile Property D^t proce- 
dure and in clsFile's Init method. 

Stan the VBDoc project by pressing the F8 key. F8, 
the Step-Into function key, starts the program on the 
first executable line in the startup form's Form_Load 
event. The yellow highlight represents the next state- 
ment to execute. Continue pressing F8, and on the 
third repetition the debugger steps into the InitSettings 
routine. Press F8 a couple more times, then use the 
Step-Out function key (Ctrl+Shift+F8) to continue 
running the program until you're back at the line in 
Form_Load following the call to InitSettings. 

Now use the Step-Over function key (Shift+F8) 
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to continue through the Form_Load routine without seeing each 
lower-level routine execute. When you step over the line in 
Form_Load that sets the default project path, VB stops at your 
breakpoint in the clsProject's ProjectFile Property Let routine: 

If InStr(UCase$(ProjectFi lename) , 
WBP") Then 

You can see how VB arrived at this point by choosing the View | Call 
Stack menu item (or by pressing Ctrl+L). You can jump into the 
code at any point in the call stack by double-clicking on a routine 
name in the list. The line labeled Non-Basic Code indicates that VB 
fired an event routine on your behalf. Continue from your breakpoint 
by pressing the Run key (F5), and the debugger then stops at the 
breakpoint in clsFile's Init method for the first file. For now, 
continue by pressing the Run key (F5) repeatedly — once for each 
file in the project — until the main form shows. 

VBDoc's key element is a pair of class modules, clsProject and 
clsFile. Restart your project and run it (F5) to the first breakpoint 
in clsProject's ProjectFile Property Let procedure. Step over each 
line (Shift+F8) until you reach the LoadFile call. Step into LoadFile 
(F8) to see how the contents of the VBP file are returned: 

Public Function LoadFile _ 

(ByVal FileName As String) As String 

Dim iFileNum As Integer 

iFileNum - FreeFile 

Open FileName For Input As //iFileNum 

LoadFile = Inputt L0F( i Fi 1 eNum) . #i Fi 1 eNum) 

Close #iFileNum 
End Function 

The Input statement reads the number of bytes specified by the 
Length of File (LOF) function. Use Step-Out (Ctrl+Shift+F8) to 
return to the ProjectFile routine. 

Next, step into the ParseProject function to load the project's 
properties and files (see Listing 1 ) . The process of reading a file and 
taking apart its contents is called parsing. ParseProject first uses the 
Split function to separate the VBP file by carriage return-line feed 
characters using the vbCrLf constant. This is a quick way of 
breaking the file into individual lines. Individual properties in the 
VBP file are composed of key-value pairs: 

CI ass=cl sProject : CProject.cls 

You loop and split each line in the file using the = character to 
separate each key name from its value, and you pick up individual 
project properties and filenames with a Case statement. You create 
an instance of clsFile in ParseProject for each file in the project, and 
you call the Init property to load and analyze the file: 

Case "FORM". "MODULE", "CLASS" 
'project files 
If colFiles Is Nothing Then 

Set colFiles = New Collection 
Set oFi 1 e = New clsFile 
oFile.Init sFileType, sFileName. 

GetPath(ProjectFile) 



colFiles. Add oFile. oFi 1 e . Fi 1 eName 
Set oFile = Nothing 

You store each file instance (one for each file in the project) in the 
colFiles collection using the filenames as collection keys. 

Continue stepping the debugger or use the Run key (F5) 
until you come to the breakpoint in the clsFile Init routine, 
where you collect file attributes and read the file contents using 
the LoadFile routine: 

m_sFi 1 eContents = LoadFile _ 

(GetFi 1 ePath(BasePath, m_sFi 1 eName) ) 

The GetFilePath function determines the physical path to your 
project files. You need this function if some of your project's source 
files come from outside your source directory. This is common in 
situations where you have a library of common modules, classes, and 
forms in a common directory that you reuse on projects. If your 
source files all come from the same directory (as with VBDoc), the 
GetFilePath function returns the project directory. Continue press- 
ing F5 to run at each breakpoint until the main form shows again. 

Parse Project Files 

Now let's look at how you collect file header comments. Click on a 
filename in the Files in Project list, and VB stops at your breakpoint 
in frmMain's ShowFileDoc routine: 

Set oFile - goProject . Fi 1 eRef( Fi 1 eName ) 
rtbProjectDoc .Text = oFile.FileHeader 
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File Tools Help 



|DAvbpj\gs0110\code\vbdoc vbp 
Files in Proj 




Select a project using the Browse button. Click 
on a file name in the Files in Piotect box to 
display its header comments. Edit the contents 
if you like in the File Contents box and dick the 
Save File button to save the changes. Once 
done, cfck Show Docs to put the formatted 
document together. Cfck Save Docs to write 
the RTF ffe out to the project directory 



J ShowDoc * 1 



Save Docs 



Documentation for Project: VBDoc 

Project Location: dAvbpj\gsOT 1 0\code\vbdoc vbp 
Description: VB Documenter Utility 
Project Title: VBDoc 
Project EXE: VBDoc.exe 
Startup object: trmMain 
Number of source lies: 7 
Project Type: Exe 

Project File: CFile.cIs 



Class Name: CFile.cls 
Description: Holds into tor tiles in the project- 
Component: VBDoc ■ VB Project Documenter 
Date Created: 30-May2001 



Figure 1 Off to a Good Start. The VBDoc utility loads properties 

and a list of included modules from a VBP (VB Project) file. You ex- 
tract the header comments from each module and edit them in the 
VBDoc form, then save the results to an RTF file that you can load in 
your favorite word processor. VBDoc doesn't finish the job of docu- 
menting your code, but it can start it. 
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The goProject.FileRef property returns a file object reference from 
the project's Files collection. Step into the oFile.FileHeader routine 
to see how VBDoc handles file header analysis: 

Public Property Get FileHeaderO As String 
'returns the File Header comments 
If Len(m_sFi 1 eHeader) = Then 
m_sFi 1 eHeader = ParseHeader( ) 
GetLineCount 
End If 

Fil eHeader - m_sFi 1 eHeader 
End Property 




Private Function ParseProject 

(ByVal FileContents As String) As Boolean 
'returns comma-delim list of project 
'files; empty string if invalid file 
Dim sLi neBuf f er( ) As String 
Dim sLi neVal ues( ) As String 
Dim sValue As String 
Dim ILine As Long 
Dim oFi 1 e As cl sFi 1 e 
'split vbp into individual lines 
s Li neBuf fer = Spl i t _ 

(FileContents, vbCrLf) 
For ILine = To UBound(sLineBuffer)-l 
If Len(Trim$(sLineBuffer 
(ILine))) Then 
sLineValues - Spl it _ 

(sLineBuffer(Uine). "=") 
If UBound(sLineValues) > Then 

sValue = Stri pQuotes ( sLi neVal ues ( 1 ) ) 
'save properties for keywords 
Select Case UCase$( sLi neVal ues ( ) ) 
Case "TYPE" 

Select Case UCase$( sVal ue ) 
Case "OLEDLL" 

m_sProjectType = "ActiveX DLL" 
' other cases here . . . 
End Select 
Case " FORM" , "MODULE " , "CLASS" 
'project files 
If colFiles Is Nothing _ 

Then Set colFiles = New Collection 
Set oFile = New els File 
oFile.Init sLineValues 
(0), sValue, GetPath _ 
(ProjectFile) 
colFiles. Add oFile. oFi le . Fi 1 eName 
Set oFile = Nothing 
Case "TITLE" 

m_sProjectTitle = Trim$( sVal ue) 
' other cases here . . . 
End Select 
End If 
End If 
Next 

ParseProject - True 
End Function 



Listing 1 The ParseProject function decomposes a VBP file into a set 
of properties and a collection of files. First it splits the file into indi- 
vidual lines, then it separates the key-value pairs to store each prop- 
erty value. You handle files by creating a file object and calling its Init 
method to get the file properties and contents. 



If the file header for this file hasn't been processed already, you call 
the ParseHeader routine to extract the comments (download List- 
ing A). ParseHeader separates the file into individual lines and 
searches for the header comment block. Header comments are 
found either between the optional delimiters or as the first contigu- 
ous block of comments. 

Finally, let's see how you create formatted output. Click on the 
Show Docs button, and VB stops at your breakpoint in frmMain's 
ShowDoc routine (download Listing B). You format text program- 
matically in the RichTextBox by selecting the text and applying 
formatting to the selected text. You use the sFormat array in ShowDoc 
to keep track of where formatting is required in the output. The 
sFormat array contains a series of comma-delimited entries that 
specify the beginning character position in the text, the offset, and a 
descriptive name for the format ("Headingl", "Heading2"). 

Step through the code in ShowDoc to see how VBDoc creates 
the output from the project and file properties. Click on this line 
near the bottom of ShowDoc: 

FormatDoc sFormat 

Use the Run to Cursor keyboard shortcut (Ctrl+F8) to run to the 
selected line. Step into the FormatDoc routine to see how the 
RichTextBox formatting is applied (download Listing C). Here, 
you loop through the sFormat array, select the appropriate text, and 
apply the appropriate font style for the format name. 

Continue running the app, and click on the Save Docs button to 
run to your final breakpoint in frmMain's CreateDocFile routine. 
You create the output file using the SaveFile method of the 
RichTextBox: 

rtbProjectDoc . SaveFi 1 e sFile, rtfRTF 

And that's it! Try enhancing VBDoc on your own by listing 
referenced objects (such as OCX files) or all the routine declarations 
in each file. Use the debugger shortcuts you've learned to debug your 
new features. Then rest easy knowing your project documentation 
chores have just gotten easier, vsm 



Stan Schultes is a project and IT manager and a VB/Web enterprise 
application architect and developer in Sarasota, Fla. Stan is an MCP in 
VB and spoke on VB development at Microsoft's DevDays confer- 
ence. He is a contributing editor for Visual Studio Magazine and writes 
regularly for it. Reach Stan at stan@vbexpert.com. 



Use these Locator-i- codes at www.vbpj.com or www. 
vcdj.com to go directly to these related resources. 

VS0110 Download all the code for this issue of VSM. 

VS0110GS Download the code for this article separately. 
The code for this article includes a complete utility to create 
VB project documentation, as well as Listings A, B, and C. 

VS0110GS_T Read this article online. DevX Premier Club 
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Don't Overuse Inheritance 



Animal classification provides a good pattern for inheritance. 



by Bill Wagner 



Technology Tool 




□ VB.NET 

□ C# 

□ SQL Server 2000 

□ ASP .NET 

□ XML 

□ VB6 

£f Other: 

Some object-oriented 
experience and a 
desire to learn more 



Resources 

Design Patterns: 
Elements of Reusable 
Object-Oriented Software 
by Erich Gamma, Richard 
Helm, Ralph Johnson, 
John Vlissides 
[Addison-Wesley, 1995, 
ISBN: 0201633612] 
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ou've probably seen examples of object-oriented 
programming that use animal classification to 
explain inheritance. If done correctly, this analogy 
works well. In this column, I'll use animal classifica- 
tion to discuss what inheritance means, when to use 
it, and when other alternatives support your particu- 
lar design better. 

One way of understanding inheritance is to use 
the phrase "is a specialization of." For example, "a 
bear is a specialization of a mammal." Biologists 
classify animals into kingdoms, phyla, classes, orders, 
families, genera, and species (see Figure 1). Software 
developers can learn a lot from this classification. It's 
based on a hierarchy that moves downward from the 
general (kingdom) to the specific (species). 

Two terms, substitutability and coupling, can help 
you understand the good and the bad of inheritance. 
Substitutability means you can use a derived class 
(bear) as a substitute anytime you expect the base class 
(mammal). In code, this means any method that 



expects a reference to a mammal works correctly with 
a reference to a bear. 

For example, suppose you're watching bats and 
flying squirrels. You might decide mammals need a 
Fly () method. Well, bears don't fly. This problem 
brings up coupling, which defines how closely two 
classes depend on each other. In the preceding ex- 
ample, the bear class and the mammal class are highly 
coupled. In fact, an inheritance relationship creates 
the highest possible coupling between two classes. 
The derived class and the base class are closely coupled. 
Any change in the base class affects the derived class, 
and any changes in implementing the base class affect 
the derived classes. 

In general, you should minimize both coupling 
and inheritance. However, inheritance provides greater 
reuse than any other technique. A bear class supports 
all the methods in the mammal class automatically. A 
bear also inherits the implementation of all the meth- 
ods in the mammal class. (See the sidebar, "Follow 



Follow These Class-Building Rules 



I like to use real-world analogies to describe object-oriented techniques. For example, children playing with 
Legos can build many different objects. The key to building so many different things with Legos is that each 
piece is small and simple. Some new Lego sets contain larger and more complicated pieces. These more 
complex pieces are interesting, but more limiting. Keep this in mind when you design objects: The simpler the 
class or interface, the more ways you can use it. When you're designing and building classes, try to keep as 
many classes as simple as possible. Follow these rules: 

• Ensure class inheritance follows the "is a" relationship. Or, use "is a specialization of" if that's easier. 

• Look out for " is almost a, " which usually implies the need for a new class to separate the nonimplemented 
functionality. 

• Look out for "works like. " This should be an interface or a contained object: the one you choose depends 
on the public requirements for the new interface. 

• Make interfaces for reusable functionality. 

• If you can get the behavior you want using containment or interfaces, use that instead of inheritance. 

• Build more complicated objects and classes only when you need them in larger projects. Each class should 
add only one piece of clearly defined functionality. 
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These Class-Building Rules," for more class- 
building information.) 

A second reason for using inheritance is 
to provide a common interface that several 
classes support. All mammals support a 
common set of behaviors, or interfaces. 
However, you can add behavior unrelated 
to a class's main putpose by defining inter- 
faces a class can support. Good examples of 
interfaces are .NET's ISerializable and IDis- 
posable interfaces. These interfaces are un- 
related to where a class fits in a hierarchy. 
Interfaces often live in the solution do- 
main. They don't represent real-world ob- 
jects or abstractions. Rather, interfaces of- 
ten represent software abstractions that 
add functionality to your real-world ab- 
stractions. An IFly interface is a good way 
to incorporate flying capability into the 
animal kingdom. Bats fly. Some birds fly. 
Some insects fly. These particular classes 
can support the IFly interface without ty- 
ing them together using inheritance. 

Understand Common 
Problems 

In real-world design, one mistake comes 
from trying to work with a hierarchy where 
a base class is too specific. For example, 
imagine you wrote the mammal base class 
after only seeing canines of various forms 
(dogs, wolves, coyotes, foxes). The first time 
you see a cat, you know it's related to dogs, 
but your mammal class has methods that 
make no sense for a cat, such as running in 
packs, barking, and growling. 

Your first instinct is to make a cat behave 
like a dog. The reason is obvious — you can 
reuse lots of code. But this inheritance will 
cause you problems. When you see yourself 
making a new derived class that doesn't 
support all the base class methods naturally, 
find a different design. The right answer is 
to break the dog class into two different 
parts: the parts common to cats and dogs, 
and the parts unique to dogs. Then, both 
cats and dogs derive from this new base class. 
Coding this kind of mistake causes you to 
downcast objects to see the actual runtime 
type of an object before you use it: 

if (pAnimal is (dog)) 
pAnimal ->bark (); 

Unfortunately, once you write this code, it's 
too late. Look for these kinds of problems 
before you start coding. 

Another mistake is using an interface as 



a base class. You'll run into problems be- 
cause you've constrained a particular behav- 
ior to one group of classes. As a result, you 
limit the clients' ability to design their own 
hierarchies. For example, consider flying 
animals. Flying is a good candidate for an 
interface. Many unrelated animals fly, in- 
cluding bugs, many birds, and bats. You 
might be tempted to create a Fly () method 
in the bird base class, but if you did, you'd 
commit the first mistake: Neither ostriches 
nor emus fly. Once again, you want to treat 
flying animals the same way, so you should 
make flying an interface. Bats, most birds, 
and many bugs can all implement the IFly 
interface. 

Maybe you're thinking interfaces let you 
reuse only an interface description, but they 
don't let you reuse implementation. This 
isn't true — you can reuse the implementa- 
tion by creating a class known as a delegate. 
This term is more generic than a C# del- 
egate, so don't confuse the two. A delegate 
class provides a common implementation 
that many different, unrelated classes can 
share. Consider the bird class again. Most 
birds fly, so it makes sense to create a class 
that can implement that ability. Then, any 
class derived from bird can contain a mem- 
ber of this FlyingBird class to reuse the 
flying capability. This move lets you reuse 
the implementation for flying birds without 



Chordata 



cluttering the bird class's public interface 
with methods not supported by all birds. 

Now look at some real classes and see 
how Microsoft .NET uses these concepts to 
create an efficient, reusable design in the 
base class libraries. The System. Collections 
namespace contains collection classes and 
interfaces to work with those collections. 
Different storage shapes and performance 
characteristics distinguish the classes. The 
interfaces define common operations sup- 
ported by different collection classes. The 
System.Collections namespace also includes 
a class that provides default implementa- 
tions of the most common interfaces. 

ArrayList, BitArray, HashTable, Name- 
ValueCollection, ObjectList, Queue, Sorted- 
List, Stack, and StringCollection are all col- 
lections of different types. These collec- 
tions implement lists, arrays, maps, and 
hash table collections. These collections all 
inherit from the System. Object class and 
don't share a common collection base class. 
The interfaces in the System. Collection 
namespace define the shared functionality 
in the collections. 

The System.Collections namespace con- 
tains several interfaces, including ICollection, 
IComparer, IDictionary, IDictionaryEnum- 
erator, IEnumerable, IEnumerator, IHash- 
CodeProvider, and IList. Each collection 
implements the interfaces meaningful to it. 




Figure 1 Classify the Animals. Notice in these object types that the common traits are 
always true, not "almost always true." Behavior not shared by all groups is moved down the 
hierarchy, which contains as many layers as necessary to make sure all members share 

common elements. 
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For instance, the HashTable and SortedList 
classes are the only collections implementing 
the IDictionary interface, which defines meth- 
ods and properties for retrieving key/value 
pairs (see which classes implement which 
interfaces in Table 1). 

Looking at the System. Collections 
namespace in isolation, you might think it 
would be simpler to use base classes instead of 
interfaces. The true power of this design 
comes out when you look outside the Sys- 
tem.Collections namespace. Many classes out- 
side the System.Collections namespace imple- 
ment the ICollection interface. The ActiveX 
Data Objects .NET (ADO .NET) Data- 
SetView and Data View classes implement 
ICollection. TheWinForms ComboBox and 
ListBox classes provide ICollection interfaces 
to data. The WebForms DataGrid class pro- 
vides an ICollection interface to examine the 
data in a grid. By using techniques other than 
simple inheritance, the .NET designers pro- 
vide much greater reuse between objects stor- 
ing groups of items. Using the IEnumerable 
interface, ICollection's base interface, you 
can write a simple function that prints items 
from a collection to the console: 

Void copy_items (IEnumerable Src){ 
IEnumerator s - 

Src.GetEnumerator (); 
While (s.MoveNext ()) 

System. Console. Write Line 
("Found 101", s. Current); 

1 

This function works for collections, listboxes, 
combo boxes, HTML data grids, and data- 
base recordsets. Even the built-in array type 
supports the IEnumerator interface. In fact, 
if you create your own collections and imple- 
ment the ICollection interface, this func- 
tion will work with your new collection. 

The System.Collections namespace also 
defines a simple class — System. Collec- 
tions.Comparer — that implements a default 
IComparer interface for all objects. This 
class provides the IComparer interface's 
default implementation and lets you use the 
default case-sensitive comparison function 
for objects. I'll now examine the advantages 
of the System.Collections namespace de- 
sign and show how it enables you to reuse 
more components with less work. 

First, consider why collections have no 
base class. You can't say anything about the 
collections that is always true about all col- 
lections and only the collection classes. Try 
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Classes 


Implemented Interfaces 




ArrayList 


IList, ICollection, IEnumerable 


BitArray 


ICollection, IEnumerable, ICIoneable 


CaselnsensitiveComparer 


IComparer 


uaseinsensiiivenasnooaerroviaer 
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IDeserializationEventListener, ICIoneable 


Queue 


ICollection, IEnumerable, ICIoneable 


SortedList 


IDictionary, ICollection, (Enumerable, ICIoneable 


Stack 


ICollection, IEnumerable, ICIoneable 


StringCollection 


IList, ICollection, ICIoneable 



Table 1 Understand System.Collections Classes and Interfaces. The System.Collections 
namespace provides a great case study in object-oriented design and inheritance. The collec- 
tions don't share a common base class; rather, they share sets of interfaces you can imple- 
ment by collections or other collection-like objects. You can decide to implement interfaces 
on a case-by-case basis. 



a few statements: "All collections, and only 
collections, can store multiple objects." This 
statement is false because many other ob- 
jects store multiple objects, including 
listboxes, XML DOM objects, data grids, 
and database tables. "All collections provide 
ways to search for objects" is also false. 
HashTables can find a key quickly. ArrayList 
provides a BinarySearch method. Database 
tables find keys. 

Performance Differs 

Note that the performance characteristics 
are different for those different objects. 
The BinarySearch () method is 0(ln n) 
performance; the HashTable.Contains () 
method is close to O(l) for good hash 
functions. The .NET designers chose not 
to make this method a base class method; 
instead, they wanted operations with dif- 
ferent performance characteristics to be 
members of different classes or interfaces. 

I don't have access to the .NET source 
code, so I need to do a litde spelunking to 
examine any contained classes in detail. If I 
were developing the classes based on the 
interface provided, the Stack, Queue, and 
ArrayList classes would each contain a private 
class to implement the core collection func- 
tionality. These three classes all use some 
form of a list or array structure inside. This 
common implementation isn't part of the 
interface, so it can be hidden safely from the 
user. All these classes might use the built-in 
array type or a collection of arrays to imple- 
ment the storage for the collections. If you 



look at mscorlib.dll with the Microsoft: Inter- 
mediate Language (MSIL) Disassembler, you 
can examine the collection classes' contents. 
Queue, ArrayList, and Stack all use a built-in 
array ofSystem.Object objects in their imple- 
mentations. 

Inheritance is a powerful tool and a key 
building block to any object-oriented lan- 
guage. Use it at the right time, and you can 
build a powerful set of classes you can reuse 
in many places. Use it at the wrong time, and 
you'll introduce special cases where code 
doesn't function the way you want, vsm 



Bill Wagner is a founder of SRT Solutions 
(www.srtsolutions.com). He has 15 years of 
programming experience, has written for Vi- 
sual C++ Developers Journal and VSM on 
C++ and C# topics, and is the author of the 
upcoming C# Core Language Little Black Book 
(The Coriolis Group). E-mail Bill at wwagner® 
srtsolutions.com. 
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A lot of boring code ro provide consistent valida- 
tion probably winds up in your apps. If I had 
ruby slippers, I'd click my heels three times and wish for 
a simple tool to do this job for all our apps. With a tool 
to provide items such as IsRequired and IsNumeric in 
the Properties window, you'd have to do nothing more 
than set these properties to have consistent event 
behavior in all your forms. 

No ruby slippers necessary: It's surprisingly easy 
to do this in Visual Basic .NET (VB.NET). You can 
link together two simple new concepts — runtime- 
defined event handlers and property extenders — to 
provide powerful functionality. 

An event is an occurrence, such as a user action, 
that causes a message to be sent to your application. 
You define an event procedure (also called an event 
handler) in your code to respond to this message. VB6 
defines event procedures by matching the event 
procedure's name with the name of the event. For 
example, Button 1 _Click handles the Button 1 control's 
Click event. 

VB.NET allows greater flexibility in hooking events 
and naming event procedures. It has at least three ways 
to hook up events: the VB6 compatibility class's pseudo 
control array classes, the Handles clause of event 
procedures, and the AddHandler function. Each ap- 
proach is more flexible than the previous. 



by Kathleen Dollard 

The compatibility class's control array classes work 
for converted code, but they aren't easy to use in new 
code or in adding controls to existing control arrays. 
You generate a Handlers clause automatically if you 
double-click on a control in VB.NET: 

Private Sub Buttonl_Cl i ck( 

ByVal sender As System. Object. 
ByVal e As System.EventArgs) Handles 
Buttonl. Click 

The default name is familiar, but you can use any name 
you want. The sender is the object that raised the 
event — in this case, the Buttonl control. The second 
parameter is an instance of the System.EventArgs class. 
In VB.NET, the second argument is either an instance 
of the System.EventArgs class or one of the classes that 
inherits from it. 

Provide an Event Procedure 

Windows.Forms declares many events in the Control 
class, which means these events are available for all 
Windows.Forms controls that inherit from the Con- 
trol class. Many of these events use the System . EventArgs 
class, although some such as KeyPress have a specific 
event argument class. You can view the control hierar- 
chy in the object browser. 
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The Handles clause can specify one procedure to handle 
multiple control events. It's the easiest way to provide a single 
event procedure for a set of controls. The drawbacks: It's 
difficult to ensure that all controls have a consistent set of 
events, and it's a design-time tool not available at run time. 

To ensure a consistent set of event procedures, setting 
them in code at run time is more reliable even if it's a bit more 
work. Use the AddHandler function to hook events to event 
procedures at run time: 

Dim Requiredt) As Control = I txttastName , txtDOB) 
Dim ctl As Control 
For each ctl In Required 
AddHandler ctl. Leave, _ 

AddressOf Requi red_Leave 
AddHandler ctl. Change, _ 

AddressOf Requi red_Change 
AddHandler ctl. Change, _ 
AddressOf Standa rd_Change 

Next 



This code adds three event procedures to all controls in the 
array. Two event procedures are raised when the ctl.Change 
event occurs. This works fine, with the only caveat being not 
to rely on the order in which the events are fired. 

The extender component model enables you to add 
specific extender properties to all, or a subset of, the controls 
on a form. These pseudo properties appear in each conrrol's 
Properties window (see Figure 1). However, the data is 
contained in the extender, not in the control itself. 

The extender class's declaration includes attributes that indicate 
it's an extender and what properties it supports: 

<ProvideProperty( "IsRequi red" . GetType( Control )) , _ 
ProvidePropertyf "MarkDi rty" , GetTypet Control ) )> 
Public Class Val i dati ngExtender 
Inherits Component 
Implements IExtenderProvider 

This extender (like most extenders) inherits from the System.- 
ComponentModel.Component, so you can add it to the toolbox 
and drop it onto a form, where it resides in the component window. 
Extenders must implement the IExtenderProvider interface, which 
contains a single method, CanExtend. The CanExtend method 
determines whether the extender properties are included for a 
particular control. 

Several things must happen for the extender properties to appear 
in a control's Properties dialog. In the component, you must declare 
the class with an attribute specifying the property, CanExtend must 
return True, and there must be a Public SetExtenderPropertyName 
and/or a GetExtenderPropertyName (see Listing 1). In the project 
where you'll use it, you must reference the component DLL, place 
the component in the toolbox through Customize Toolbox (right- 
click on the toolbox), and drag an instance of the control onto your 
form. .NET beta 2 has a glitch where the extender sometimes 
behaves badly if you don't place the extender DLL in rhe solution 
folder or register it in the global assembly cache. 

VB persists these extender properties automatically with the form. 
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Figure 1 Add Extender Properties. Turn on automatic and consistent vali- 
dation by simply dropping a component on your form and setting properties. 
Create an extender that adds new properties to the Properties dialog for con- 
trols on your form, and add consistent event handling for validation or other 
purposes to your control when you set these properties. 



You need additional attributes only for special persistence handling. 
Similarly, the extender properties appear in the Properties window by 
default, but you can suppress them through additional attributes. 

You access extender properties differently through code because 
they belong to the extender, not the control. You might want to set 
these properties at run time, perhaps using the database field types 
to determine appropriate validation. This is perfectly valid, but you 
must use this syntax: 

Val i dati ngExtender . Set IsNumeri c( txtVi si ts , True) 

Unfortunately, an IDE bug in beta 2 results in an IDE crash if you 
paste a control onto a form using an extender. This problem occurs 
with your extenders, the VB6Compatibility library control array 
extenders, and the tooltip extender. 

Hook Up Events 

The component in Listing 1 does the real work. It's responsible for 
hooking up the events and the event procedures. It also keeps track 
of the objects and their extender properties using a hash table 
(collection). 

SetlsRequired and SetMarkDirty are called automatically when 
the class is created at both design time and run time. These methods 
contain logic to determine whether the event procedure should be 
hooked to the event, and they call AddHandler to add the hook if 
needed. Checking the DesignMode status keeps the event proce- 
dures from being added at design time. 

The SetMarkDirty procedure demonstrates an undocumented 
feature of events raised in classes, which Bill McCarthy showed me. 
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A hidden delegate (the VB.NET style pointer to a function) is created 
at compile time for each declared event. This delegate is named with 
the event name, followed by "Event" (<eventname>Event; for ex- 
ample, MarkDirtyEvent). 

When you can use this delegate to hook up events, the event is 
raised directly in the form and isn't raised in the extender. This trick 
in an extender component is an efficient way to have the same event 
procedure in your code fire by multiple controls on your form 
identified by extender properties. 



You can hook up as many events to the control as you like. This 
means you can have both default handling specified in your extender 
and control-specific handling specified in the form for the same 
control event. You can also add normal methods and properties to 
the extender component, just as you would any other class. 

You can customize the component class shown in Listing 1 to 
match your own style of control validation. Numerous approaches 
to validating data rely on specific events being fired, and this listing 
shows only how to ignore non-numeric keystrokes. 



Option Explicit On 
Option Strict On 

Imports System 
Imports System. Col lections 
Imports System. ComponentModel 
Imports System. Windows 
Imports Microsoft. VisualBasic 

' Class declaration 

<ProvideProperty( " IsNumeri c" , GetType _ 
( Forms .Control )) , ProvideProperty _ 
("MarkDirty", GetType( Forms . Control ) )> 
Public Class Val idatingExtender 

Inherits ComponentModel .Component 
Implements IExtenderProvider 

Public Event MarkDirty As EventHandler 

Private mlsNum As New HashtableO 
Private mMark As New HashtableO 

#Region "Component Designer generated code" 

Public Function CanExtendt _ 

ByVal extendee As Object) As Boolean _ 
Impl ements I ExtenderProvider. Can Extend 
Return (TypeOf extendee Is Forms . Control ) 
And (Not TypeOf extendee Is Forms. Label) 
And (Not TypeOf extendee Is Forms. Form) 
And (Not TypeOf extendee Is Forms . Button ) 

End Function 

<ExtenderProvidedProperty( ) . Description 
("Numeric Entry?"), Categoryt "Val idation" )> 
Public Function GetlsNumerict 
ByVal ctl As Forms . Control ) As Boolean 
Return CBool (mlsNumtctl ) ) 

End Function 

<ExtenderProvidedProperty( )> Public Sub 
SetlsNumerictByVal ctl As Forms . Control , 
ByVal IsNum As Boolean) 
Dim IsSet As Boolean 
If Not ctl Is Nothing Then 

If (Not mlsNum(ctl) Is Nothing) Then 

IsSet = CBool (mlsNumtctl )) 
End If 

mIsNum(ctl ) = IsNum 



If Not DesignMode Then 

If IsNum And Not IsSet Then 
AddHandler ctl . KeyPress , _ 
AddressOf Me.Num_KeyPress 
'More handlers as needed 
El self Not IsNum And IsSet Then 
RemoveHandl er ctl . KeyPress , _ 
AddressOf Me . Num_KeyPress 
'Remove additional handlers 
End If 
End If 
End If 
End Sub 

<ExtenderProvidedProperty( ) , Description _ 
("Dirty event raised?"). Category _ 
("Validation")> Public Function GetMarkDirty 
(ByVal ctl As Forms . Control ) As Boolean 
Return CBool (mMarktctl ) ) 

End Function 

<ExtenderProvidedProperty( )> Public Sub 
SetMarkDi rtytByVal ctl As Forms . Control , 
ByVal bMark As Boolean) 
Dim IsSet As Boolean 
If Not ctl Is Nothing Then 

If (Not mMark(ctl) Is Nothing) Then 

IsSet = CBool (mMark(ctl ) ) 
End If 

mMarkfctl ) = bMark 

If Not DesignMode Then 

If bMark And Not IsSet Then 
AddHandler ctl . TextChanged , 
Me. MarkDi rtyEvent 
El self Not bMark And IsSet Then 
RemoveHandl er ctl . TextChanged . 
Me. MarkDi rtyEvent 
End If 
End If 
End If 
End Sub 

Private Sub Num_KeyPress ( ByVal sender As 
Object, ByVal e As Forms . KeyPressEventArgs ) 
'Sample of event proc. 
e. Handled = ((e.KeyChar < "0") Or _ 
(e.KeyChar > "9")) And _ 
(e.KeyChar <> ".") And _ 
(e.KeyChar <> Control Chars . Back) 
End Sub 



Listing 1 This is the entire VB.NET class for an extender that provides event handling based on Properties dialog entries (assuming you create 
it as a component class, which sets the auto-generated code section in the "Component Designer generated code" region). You can create 
additional extender properties similar to IsNumeric (where the event handler resides in this class), MarkDirty (where the event handler 
resides in your form), or a combination of the two techniques. The Num_KeyPress event procedure shows an example of an event procedure 
in this class and demonstrates how you ignore a user's keypress in VB.NET. 



80 



VISUAL STUDIO MAGAZINE • OCTOBER 2001 • www.vbpj.com • www.vcdj.com 



The extender 
component model 
enables you to add 
specific extender 
properties to all, or a 
subset of, the controls 
on a form. 

Once you make one or more of these components, you can 
include them in any form where you want consistent event han- 
dling. Simply place the extender component on your form, set the 
extender properties in the Properties window or through code, and 
go on to work on more interesting parts of your program. 

You'll probably find other uses for the flexibility in VB.NET 
event handling. Previous event/control array limitations — such as 
placing a control in only one array, single-dimensional arrays, static 
groups of controls, a single event procedure for each event, binding 



event procedures for the life of the control, and having an event 
handle only objects of a certain class — are all gone. 

You need to let go of old habits and out-of-date practices to take 
full advantage ofVB.NET. Instead of phrasing the problem in an 
obsolete manner, such as "replacing control array behavior" (which 
you can also do with this technique), drill down to the underlying 
problem and explore how VB.NET can solve the problem in 
potentially better ways, usm 



Kathleen Dollard is an independent consultant in Fort Collins, Colo. 
She's a moderator on the DevX forums (http://news.devx.com) and a 
Microsoft MVP. You can reach her at kathleen@mvps.org. 



Go Online 



Use these DevX Locator+ codes at www.vbpj.com or 
www.vcdj.com to go directly to these related resources. 

VS0110 Download all the code for this issue of VSM. 

VS0110DT Download the code for this article separately. 
This article's code includes the extender class and a test 
project that demonstrates its use. 

VS0110DT_T Read this article online. DevX Premier Club 
membership is required. 

Want to subscribe to the Premier Club? Go to 

www.devx.com. 
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AWARD-WINNING COMPONENTS 
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FarPoint's 

Button Objx 2 

Create fu% customized buttons, toolbars and custom-shaped containers 

FarPoint's Button Objx enhances any web or Windows application. Not only can you replace 
the Windows button control to create visually enhanced buttons, you can create fully 
customized active buttons and toolbars as well as custom-shaped containers. 

> Create active-style buttons with or without 3D borders 

> Create a toolbar or tool palette 

> Includes a help balloon (tool tip) for displaying customized text 



FarPoint's 

Calendar 



Objx 3 



» 



Adding custom calendar and time input to your application has never been this easy 
FarPoint's Calendar Objx 3 gives you all the components your development team needs to 
display or select date and/or time values in any application. By including a calendar con- 
trol, a clock control, a poster control, and a schedule control, Calendar Objx makes it 
easy to incorporate robust calendar or schedule features in your program's interface. 

> Choose from multiple calendar display formats 

> Customize all calendar elements 

> Includes five AutoStyles to help you create commonly used calendar looks 





FarPoint's 

Input Pro 3 

Full-featured edit components for precise data input 

Easily create professional data-entry screens using Input Pro's eight custom controls. Take 
advantage of the six formatted edit controls to quickly validate data and alert your user as 
they enter information or as the application programmatically assigns or edits values. 

> Choose from six edit controls (Currency, DateTime, DoubleSingle, Longlnteger, 
Mask, or Text) 

> Create your own appearance or choose from predefined styles 

> Includes a Memo control and Boolean control 



Version! 



It's an Enhanced Grid... 

Spread is the best grid to use to present and 
format tabular or database information in a 
format your users want. 

> Bind using the most popular data sources or 
populate in unbound mode 

> Create a grid with up to 2 billion rows by 2 billion columns 

> Provide the most popular data and database formats using 1 2 cell types 

> Increase data access speed by using the Virtual Data Manager 

> Increased control by validating when and what data gets written 
to the database 




It's a Spreadsheet... 

Spread is the best spreadsheet to use to 
offer advanced spreadsheet functionality 
your users need. 

> Import and export spreadsheet files in 
Microsoft Excel 97/2000 or many 

other formats 
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> Export spreadsheet files as XML or 
HTML files 

> Use one of 1 05 named functions or create 
user-defined custom functions 

> Sort with up to 256 sort keys 



FOR THE PROFESSIONAL DEVELOPER 
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FarPoint's 

List Pro 3 

The ultimate data viewer 

FarPoint's List Pro contains the most powerful list box and combo box development compo- 
nents. These extremely robust controls allow you to display up to two billion list items, display 
single records or items on multiple rows, merge cell text for easier viewing, search for specific 
list items, or sort list items using unlimited keys. 

> Display data in single or multiple columns 

> Merge column cells that contain identical text 

> Choose an automatic search method 
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FarPoint's 

Tab Pro 3 

Speed, ease of use, and its extensive features make this the "tab of choice" 

Tab Pro is the easiest and quickest way to enhance your application's appearance using a tab 
metaphor. Whether taking advantage of its eight pre-defined appearance styles or dynamically 
changing the tab's appearance in response to your user, Tab Pro gives you the most compre- 
hensive tab feature set to customize any application. 

> Choose from eight pre-defined appearance styles 

> Design time support for setting pictures, plus metafile support 

> Create a book chapter effect by assigning multiple pages to one tab 



New Bundles 

» Enterprise Developer Toolbox - MSRP $849 

Spread, List Pro, Input Pro, Tab Pro, Button Objx, 
Calendar Objx 

» Enterprise Database Pack - MSRP $579 

Spread, List Pro, Input Pro 




Purchase your copies today by calling 
800-645-5913 
or download fully functional trial 
versions from our website. 
www.fpoint.corn 
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TECHNOLOGIES INC 



www.fpoint.com 

FarPoint's Spi*0dCl 3*5 



J 



It's a Report Writer.., 

Spread is the best report writer to use to preview and print data in the 
format your users expect. 

> Use the Print Preview control to see how your printed spreadsheet will look 

> Print a block of cells, a range of pages, or only the columns and rows that 
contain data 

> Create custom print configurations by specifying 
margins, page orientation, borders, gridlines, colors, 
and shadow effects 

> Print multiple spreadsheets on a single page 

> Add headers and/or footers to your printed pages 



It's So Much More. 



Purchase today by calling 
800-645-5913 

or contact your 
favorite reseller. 
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Cure Your Dates of 
Culture Shock 



by Jonathan Goodyear and Robert Teixeira 



Technology Too 



a' VB.NET 

tfc# 

a' SQL Server 2000 
a' ASP .NET 
□ XML 
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SQL Server 7.0 
.NET Framework 



Q« Format International Dates 

My company plans to deploy an application globally. 
I experienced many problems with dates in this app 
during initial testing because of different date for- 
mats. How can I format the dates so users see the 
correct representation for their region? 

A: 

The problem here is that different countries use 
different date formats. Windows recognizes three: ml 
d/y, d/m/y, andy/m/d. VB makes assumptions about 
which format to use when it implicitly converts your 
binary date variables to strings for display, and it 
doesn't let you specify the one you want. You must 
use an API call to format the date based on a combi- 
nation of cultural and regional information. Each 
language and country setting is represented by a 
numerical Locale ID (LCID), and you must query 
the client for what Locale setting to use. If the client 



VB4, VB5, VB6 • Convert a Date to String 



Public Const S_0K = 

Public Const VARIANT_NOUSEROVERRI DE - &H4 

Public Declare Function VariantChangeTypeEx Lib "oleaut32" _ 
(ByRef destVar As Variant, ByRef srcVar As Variant, 
ByVal LCID As Long, ByVal wFlags As Integer, 
ByVal VarType As Long) As Long 

Public Function DateToString (ByVal dt As Variant, ByVal LCID 
As Long) As String 

Dim IngRetVal As Long 
Dim strDate As Variant 

IngRetVal - Va ri antChangeTypeEx ( dt , strDate, LCID. 
VARIANT_N0USER0VERRI DE , vbString) 

If IngRetVal = S_0K Then 
DateToString = strDate 
Else 

' IngRetVal = Win32 Error Code 
End If 
End Function 



Listing 1 1f formatting dates for your global app makes your head spin, use 
the VariantChangeTypeEx API function to change the date into a string. But 
first you must determine what Locale ID (LCID) you need. 



is a Windows application, you can use the GetThread- 
Locale or GetUserDefaultLCID API function: 

Public Declare Function _ 

GetThreadLocal e Lib "kernel 32" _ 
( ) As Long 

Public Declare Function _ 

GetUserDefaultLCID Lib "kernel32" _ 
() As Long 

If your client is a Web browser, you can use this 
query in ASP: 

Request. ServerVari abl es _ 
( "HTTP_ACCEPT_LANGUAGES" ) 

This returns a Language-Country code string. Refer 
to the Locale ID chart to translate this code into an 
LCID (see Resources). 

The next step: Use the VariantChangeTypeEx 
API function to change the date into a string (see 
Listing 1). If you wrote your application using 
.NET, your job is easier because the .NET Frame- 
work comes with built-in cultural/regional sup- 
port. You can use the .NET Class Library's Culture- 
Info class from either VB.NET or C#. Here's the 
VB.NET version: 

Imports System. Global ization 

Public Function DateToStri ng( _ 

ByVal dt As Date, ByVal LangCode 

As String) As String 

Dim ci As New Cul turelnf o( LangCode) 

Return dt.ToStringtci ) 
End Function 

You can download the C# code (Listing A) from the 
VSAfWeb site; see the Go Online box for details. This 



Resources 



Locale ID (LCID) chart: http://msdn. microsoft. 
com/library/default.asp?url=/library/en-us/ 
scri pt56/html/vsmscLCID.< 



sp 
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Figure 1 Render the Results. You can build 

this list using a dynamically created Repeater My Family: 

server control. Trap the events for each item 

in the ArrayList data source to render the Jon 

same results you'd get if you were to use j Q y 

an actual template in your ASP .NET page. ; qj 

Ginger 
Chene 



class takes the RFC 1766 standard Language-Country string code 
automatically, so you don't need to convert it to an LCID. The Date 
(DateTime in C#) type's ToStringO method can use this class to 
determine the correct string format. — R. T. 

Track Down Bugs 

I'm up against a particularly bad and sporadic bug. I can trap errors, 
but how can I find the series of events that lead up to the error? 

A: 

Having rich error information is nice, but sometimes it's not enough 
to track down bugs. This is particularly true if you write reusable 
functionality, especially components. The .NET Framework pro- 
vides many classes usable by all .NET-compliant languages to aid in 
program diagnostics. In this case, it sounds like a stack trace is in 
order. Stack tracing, analogous to opening the Call Stack window 
in VB6, allows you to view the list of function calls that lead up to 
the currently running function (in this case, the one with the error). 

The Exception class, which has an available instance whenever 
an error occurs, sports a StackTrace property that's simply a string 
containing the fully qualified names of all the methods currently in 
execution. The string also contains the name of the source file and 
line number where the error occurred if the information is available. 
If you need a stack trace when there's no error, use Environ- 
ment.StackTrace instead. 

If you need more information, use an instance of a StackTrace 
class. From the StackTrace object, you can identify the number of 
frames in the stack and retrieve a StackFrame object for each one. 




Imports System. Diagnostics 



Dim st As New StackTrace!) 
Dim i As Integer 
Dim sf As StackFrame 

For 1 = To st. FrameCount - 1 
sf = st.GetFramet i ) 

' print line # and function name 
Console. Writet 

sf .GetFi 1 eLi neNumber( ) . ToStri ng( ) + " : ") 
Console. Write Li net sf .GetMet hod . Name ) 
Next i 

Listing 2 Stack tracing, analogous to opening the Call Stack 
window in VB6, allows you to view the list of function calls that 
lead up to the currently running function — in this case, the one 
with the error. 



You retrieve the frames in reverse order, starting with the last 
function pushed. Each frame contains the information for one of 
the function calls, such as the name of the function, its parameters, 
and the current line number in the source code of the executing 
command if the information exists (it's extracted from the debug 
symbol information) . Check out the VB.NET and C# examples of 
printing a stack trace to the console window (see Listing 2 and 
download Listing B). Simply copy the code into any function to 
see it work. 

For more power in execution diagnostics, refer to the .NET 
documentation on the Framework's Trace and TraceListener 

classes. — R. T. 

C^S Create Server Controls Dynamically 

Can you dynamically create server controls, such as the Repeater, 

that use templates? 

A: 

Why, certainly! You can create most server controls dynamically 
rather easily. For example, you would represent a typical Label 
control with this server tag: 

<asp:Label id="labell" runat="server" /> 

Create label controls dynamically like this: 

Dim labell As Label - New LabelO 
labell.ID = "labell" 
Controls. Add(labell) 

Server controls, such as the Repeater, that leverage templates are a 
little trickier. Let's give it a shot. I'll present VB.NET code here, but 
you can find a C# version online (see the Go Online box for details) . 

First, you need some data for your Repeater to bind to. An 
ArrayList collection does the trick: 

Dim al As ArrayList = New ArrayListO 

al .AddC'Jon") 

al .AddCJoy") 

al .Add("CJ") 

al .Add( "Ginger" ) 

al .AddCCherie") 

Next, instantiate a Repeater control object and assign its 
DataSource property to the ArrayList object you just created: 

Dim r As Repeater = New RepeaterO 

r. DataSource - al 

You might not have realized it before, but when you create 
templates for your server controls, they act as an event handler (of 
sorts). So you must subscribe to the proper events to handle 
everything dynamically. You can hook into the Repeater control's 
ItemCreated event with this code: 

AddHandler r . ItemCreated , 

AddressOf repeater_ItemCreated 
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You'll see the implementation of the repeater_ItemCreated event a 
bit later. First, you must fool the Repeater control a bit. The 
ItemCreated event you just subscribed to fires only for the 
ItemTemplate and Alternating! temTemplate templates. These tem- 
plates are all you need to handle the Repeater's bound data source. 

To get the ItemCreated event to fire for the HeaderTemplate, 
FooterTemplate, and SeparatorTemplate templates, specifically 
assign their respective properties in the Repeater control. These 
properties require an object that implements the ITemplate inter- 
face. The TemplateBuilder class supports this interface, so you 
create a new TemplateBuilder object instance and assign it to the 
HeaderTemplate, FooterTemplate, and SeparatorTemplate prop- 
erties of the Repeater control: 



New Tempi ateBui 1 der( ) 



Dim tb As TemplateBuilder 
r. HeaderTemplate = tb 
r . FooterTempl ate = tb 
r . SeparatorTempl ate = tb 



To bind the ArrayList to the Repeater control, you need to call 
its DataBind method. Then you render it to the page by adding it 
to the controls collection of one of the server controls on your ASP 
.NET page: 

r.DataBindf ) 

body .Control s . Add( r ) 

In the preceding code, "body" refers to a Panel server control on 
your ASP .NET page: 

<html> 
<head> 

<title>Dynamic Repeater • VB</title> 
</head> 



<body> 

<asp:panel id= 

</body> 

</html> 



body" runat="server" /> 



You've now seen how to set the gears in motion. Take a look 
under the hood of the repeater_ItemCreated event handler (see 
Listing 3) — this is where all the rendering decisions are made for 
each of your virtual Repeater templates. All the Repeater's 
templates raise the same ItemCreated event, so the same event 
handler will handle them. Determine which template raised the 
event by interrogating the ItemType property of the Repeaterltem 
object reference contained in the RepeaterltemEvenrArgs event 
parameter; you'll find it's a member of the ListltemType enu- 
meration. You can now add the proper information to the 
Repeaterltem's Controls collection, which the ASP .NET en- 
gine renders to the browser. 

Of particular note is the Repeaterltem object reference's Dataltem 
property, which contains the current item in the Repeater control's 
data source (in your case, the ArrayList object). The repeater_ltem- 
Created event handler gets fired for each item in the data source. It's 
also fired once for each item so you can handle the Separator 
template, as well as once each for the header and footer templates. 



Private Sub repeater_ItemCreated(Sender As Object, e As 
RepeaterltemEventArgs ) 
'determine which template fired the event 
Select Case e. Item. ItemType 
Case ListltemType. Header 

e. Item. Control s .Addfnew LiteralControl ("<b>My 
Family:</bXhr />")) 
Case ListltemType. Item 

e. Item. Controls. Addfnew Li teral Control (e. Item. _ 
Dataltem. ToString( ) ) ) 
Case ListltemType.Al ternatingltem 

e. Item. Controls. Addfnew Li teral Control ( "<i >" & _ 
e. Item. Dataltem. ToStringf) & "</i>")) 
Case ListltemType. Footer 

e . Item. Control s .Addfnew Li teral Control ( "<hr />")) 
Case Else ' ListltemType. Separator 

e. Item. Control s .Addfnew Li teral Control ( "<br />")) 
End Select 
End Sub 



Listing 3 Trap the ItemCreated event of the Repeater control to 
render output to the browser. Determine which template fired 
the event by interrogating the RepeaterltemEventArgs, then 
construct the proper output. 

There you have it: server controls with templates created dy- 
namically (see Figure 1 ). You can apply the same logic to other server 
controls that use templates, such as the DataList and DataGrid 
server controls. — /. G. 

Q. Can't Get a Date 

I'm trying to select items from a table that were created today using 
the SQL Server GETDATE() function, and no results come back. 
What's wrong? 



A: 



The name of SQL Server's GETDATE() function is really a misno- 
mer. It returns not only the month, day, and year of the current date, 
but it also returns the exact system time, down to one three-hundredth 
of a second. Run this script in Query Analyzer to see what I mean: 



CREATE TABLE bits 
( 



i tem_name 

created_dt 

) 



VARCHAR(IO). 
SMALLDATETIME 



INSERT bits VALUESCItem 1 ' , GETDATEf ) ) 
INSERT bits VALUESCItem 2 ' .GETDATEf ) ) 
INSERT bits VALUESCItem 3 ' , GETDATE ( ) ) 

This simple table contains three rows, each of which contains 
today's date in its created_dt field because you just ran the script. 
But you won't get any rows back if you run this query: 

SELECT 

b . i tem_name 
FROM 
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Drastically Save Development Time 

Understand the big picture with top-level 
summary reports • Understand individual objects 
with drill-down detail reports • Get up-to-speed 
quickly on inherited projects 

Dramatically Improve Quality & Performance 

Faster, scalable apps with detailed performance 
analysis • Deliver more reliable apps by detecting 
errors & omissions • Ensure data consistency and 
integrity 

Start relaxing - Call today Total SQL Analyzerl 
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bits b 
WHERE 

b.created_dt = GETDATE ( ) 

This query looks only for rows that were 
created at the exact instant the query was run. 
To get the query to execute with your proper 
intent, you must strip off the time and query 



tiiii 



SET @end_dt - 

CONVERTt SMALLDATETIME , 
C0NVERT(VARCHAR(2), 

MONTH(DATEADD(d , 1 , GETDATE ( ) ) ) 
+ '/' + 

CONVERTt VARCHAR( 2 ) , 

DAY ( DATEADDt d , 1 , GETDATE ( ) ) ) ) 
+ V + 

01 



creating two date-range constants: 



YEAR(DATEADD(d,l .GETDATE ( ) ) ) ) 



DECLARE 

@start_dt 
@end_dt 



SMALLDATETIME. 

SMALLDATETIME 



SET @start_dt = 

CONVERT ( SMALLDATETIME , 
CONVERTt VARCHARf 2 ) , 

MONTH(GETDATE( ))) 
+ '/' + 

CONVERTt VARCHARt 2 ) , 

DAY ( GETDATEt ) ) ) 
+ '/' + 

CONVERTt VARCHARt 4 ) , 
YEARt GETDATEt ) ) ) 



What you're doing here is constructing a 
date from scratch based on its individual 
component parts. To do that, you must 
convert each date part from an INT to a 
VARCHAR, then concatenate them together 
with a slash "/" date delimiter. Finally, you 
convert the concatenated string value back 
into a SMALLDATETIME data type. You 
didn't specify any time values in the date 
string, so they'll all be set to zeros. 

You could use the DATEPART() func- 
tion as an alternative to the MONTH(), 
DAY(), and YEAR() functions. The 
@start_dt constant contains today's date 
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with the time stripped off; the @end_dt 
constant contains tomorrow's date with 
the time stripped off. If you use these two 
constants as date endpoints, you can per- 
form a date range query to get the result 
you want: 

SELECT 

UtlJl 

FROM 

bits b 

WHERE 

b.created_dt >= @start_dt 
AND b.created_dt < @end_dt 

This query returns all three rows from the 
"bits" table. Notice you didn't use the BE- 
TWEEN predicate. This would've included 
tomorrow at midnight as part of the allow- 
able values. — -/. G. 
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Easy E-Mail— 
It's About Time 



Sending e-mail using ASP .NET is so simple, you'll be happy 
to e-mail-enable your applications. 




by A. Russell Jones 
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default.asp?url=/nhp/ 
default.asp?contentid 
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• A Guide to .NET: www. 
evx 



he e-mail capabilities in .NET are much more 
robust than what was available in classic Active 
Server Pages (ASP). It's difficult to see how sending 
Simple Mail Transfer Protocol (SMTP) e-mail using 
ASP .NET could be any easier. 

You can send a simple e-mail message with a single 
line of code. You send an e-mail message by calling 
the SmtpMail object's Send command with four 
String parameters: the source account; the destina- 
tion account; a subject, which appears on the Subject 
line in the destination account's mail 
program; and the message body: 



<!@ Page Language="C#" 

AutoEventWi reup="f al se"%> 

<% 

System. Web .Mai 1 .SmtpMail .Send ( 
"f romaccount@somepl ace . com" , 
"toaccount@somewhereel se. com" , 
"Thi s is the subject . " . 
"This is the message."); 

%> 

The Send method is overloaded, so 
you can create more complex messages. 
This example uses the Page_Load event 
in a code-behind VB.NET module to 
send a message with an attachment when 
the Page object loads: 

■ 

Imports System. Web. Mai 1 
' ... standard WebForm 
' initialization code here 
Private Sub Page_Load(ByVal sender 



As System. Object , ByVal e As _ 
System. EventArgs ) Handles MyBase.Load 
Dim ms As New Mai 1 Message! ) 
Dim matt As New Ma i 1 Attachment _ 

( "c r\junk.txt " ) 
ms.To = "arjl@northstate.net" 
ms.From = "arjiii@hotmail.com" 
ms.Body = "This is a test message." 
ms . BodyFormat - Mai 1 Format .Text 
ms. Subject = "Test message" 




AtUchmtM |c \some(H 1<1 



someone@someplace. com 






someoneelse@someplaceelse com 






Tes! Message 




This is a teat message. 










•I 
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Figure 1 Let Users Send an E-Mail. Users fill out the From, To, Sub- 
ject, and Message fields on the example WebForm just as they do 
with any e-mail application. The WebForm aiso contains an 
HtmllnputFile control (the last control). Note that the File Field adds 
the Browse button automatically. Clicking on the Send button sub- 
mits the form. 
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ms .Attachments .Add (matt ) 
SmtpMai 1 . Send(ms ) 
End Sub 

Let Users Send E-Mail 

You can create a WebForm easily that users fill out to send e-mail 
from your Web site. The userEmail.aspx WebForm example lets 
users fill out the contents of an e-mail message. (See Listing 1 and 
Figure 1, and download the code project from the KW Web site; 
see the Go Online box for details.) Although you would normally 
set the target address automatically, the example WebForm lets you 
enter a target address so you can test the program easily. 

The WebForm also lets users include a single attachment — but 
you need to know a couple tricks to make this work. Several standard 
WebForm Label and TextBox controls are on the form, as well as a 
standard WebForm button control that submits the data. However, 
the last control, labeled "Attachment" in Figure 1 , isn't a WebForm 
server control — it's an HtmllnputFile control. (The HtmllnputFile 
control is actually two controls — a combination of an input text 



field and a Browse button.) 

It's convenient to have controls run as server controls, but 
unfortunately, dropping an HtmllnputFile control from the Toolbox 
onto the WebForm designer disables the runat property in the 
Properties window (see Figure 2). In the example, I set the 
HtmllnputFile control's name property to txtAttachment. Even 
worse, Visual Studio doesn't add the control to the list of controls 
it creates for the page in the code-behind module. Don't worry. You 
can fix both problems manually. 

With the WebForm in design mode, click on the HTML button 
to view the WebForm HTML source code. Find the HtmllnputFile 
control (look for an <INPUT> tag that has the type="file" attribute) 
and add the attribute runat= "server": 

<INPUT id="txtAttachment" runat-"server" 
style-"Z-INDEX: 114; LEFT: 108px; 
WIDTH: 522px; POSITION: absolute: 
TOP: 330px: HEIGHT: 22px" type= 
"file" size="67"> 



• Users 



<%@ Page Language-"vb" AutoEventWi reup-"f al se" 

Codebehind-'userEmai 1 .aspx.vb" 

Inheri ts="dotNetEmai 1 . userEmai 1 "%> 
<!D0CTYPE HTML PUBLIC 

"-//W3C//DTD HTML 4.0 Transi t 1 onal / / EN "> 
<HTML> 
<HEAD> 

<titlex/title> 

<meta content="Microsoft Visual Studio.NET 7.0" 

name-" GEN ERAT0R"> 
<meta content="Visual Basic 7.0" 

name="C0DE_LANGUAGE"> 
<meta content="JavaScri pt" 

name="vs_def aul tCl ientScript"> 
<meta content="http: //schemas .mi crosof t .com/ 

intel 1 isense/ie5" name="vs_targetSchema"> 
<LINK href-"Styl es . ess" type="text/css" 

rel-"stylesheet"> 
</HEAD> 

<body bgColor="#ffffcc" 

MS_POSITIONING="GridLayout"> 

<form id-"Forml" method="post" runat-'server" 
enctype="mul ti part /form- data" > 

<asp:label id="lblDirections" styl e="Z- INDEX : 
101; LEFT: 36px; POSITION: absolute: TOP: 
25px; Design_Time_Lock: True" runat="server" 
Wi dth="632px" Hei ght=" 19px" Desi gn_Time_Lock= 
"True" CssClass="directions">Label</asp:label> 

<asp:textbox id-"txtMessage" styl e="Z - INDEX : 109; 
LEFT: 109px: POSITION: absolute; TOP: 152px" 
runat="server" Wi dth="438px'' Height- 
"161px"X/asp:textbox> 

<asp:textbox id="txtSubject" styl e="Z • INDEX : 108; 
LEFT: 109px; POSITION: absolute; TOP: 119px" 



runat-'server" Width-' 
"24px"X/asp: textbox> 
<asp:textbox id-"txtTo" 
LEFT: 109px; POSITION 
runat="server" Width-' 
"24px"X/asp:textbox> 



437px" Height- 

Style='Z-INDEX: 107: 

absolute: TOP: 86px" 
437px" Height- 



<asp:label id="lblMessage" style="Z-INDEX: 105; 
LEFT: 36px; POSITION: absolute; TOP: 150px; 
Design_Time_Lock: True" runat="server" 
Desi gn_Time_Lock=" True" CssCl ass-"smal 1 1 abel "> 
Message</asp: 1 abel > 

<asp:label i d="l bl Subject" styl e="Z- INDEX: 104; 
LEFT: 36px; POSITION: absolute; TOP: 121px: 
Design_Time_Lock: True" runat="server" 
Desi gn_Time_Lock=" True" CssCl ass="smal 1 1 abel "> 
Subject</asp: 1 abel > 

<asp:label id="lblTo" style-"Z-INDEX: 103; LEFT: 
36px; POSITION: absolute; TOP: 86px; 
Design_Time_Lock: True" runat="server" 
Width="60px" Hei ght="19px" Design_Time_Lock- 
"True" CssCl ass="smal 1 1 abel ">To</asp : 1 abel > 

<asp: 1 abel i d=" 1 bl From" styl e="Z- INDEX : 102; 
LEFT: 36px; POSITION: absolute; TOP: 55px; 
Design_Time_Lock: True" runat-'server" Width- 
"60px" Height="19px" Design_Time_Lock="True" 
CssCl ass="smal 1 1 abel ">From</asp: 1 abel > 

<asp:textbox id="txtFrom" style="Z-INDEX: 106; 
LEFT: 109px; POSITION: absolute; TOP: 55px" 
runat-'server" Width-"437px" Height="24px"> 
</asp: textbox> 

<asp:button id="btnSend" styl e="Z - INDEX : 110; 
LEFT: 438px; POSITION: absolute: TOP: 359px" 
accessKey="S" runat="server" Width="108px" 
Height="24px" Text="Send" BorderWi dth="3px" 
Border Sty 1 e=" Out set" ></asp:button> 

<asp: 1 abel i d="l bl Attachment " styl e="Z- INDEX : 
111: LEFT: 28px; POSITION: absolute: TOP: 
328px" runat="server" Width="61px" 
Hei ght="19px">Attachment</asp: 1 abel > 

<INPUT id="txtAttachment" runat="server" 
style="Z-INDEX: 114; LEFT: 108px: WIDTH: 
522px; POSITION: absolute; TOP: 330px; HEIGHT: 
22px" type="file" size="67"> 

</f orm> 

</body> 

</HTML> 



Listing 1 The generated HTML for the userEmail.aspx WebForm contains several WebForm controls and one HtmllnputFile control (the last 
control). If you want to access an HtmlFilelnput control with code after dragging it onto a WebForm, you must add the runat="server" attribute 
manually to the generated HTML. 
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Next, navigate to the code-behind module (called userEmail.- 
aspx.vb in the example) and add this line: 

Protected txtAttachment As _ 

System.Web.UI . Html Control s . Html InputFile 

Declaring the control lets you access the control's propetties in the 
code-behind module just as you can any other WebForm control. 
Note that you only need to do this if you're using code-behind 
modules — it's not necessary to declare the control if you're using 
embedded code. 

You need to collect the field values from the form to send the 
message. When a user clicks on the Send button, the form posts the 
entered data back to the server and fires the btnSend_Click event 
(see Listing 2). 

Despite the simplicity of sending e-mail, messages can fail. For 
example, the SMTP server refuses to send an e-mail if the sender's 




Imports System. Web. Mail 

' ... standard WebForm 

' initialization code here 

Private Sub btnSend_Cl ick(ByVal sender _ 
As System. Object, ByVal e As _ 
System. EventArgs) Handles btnSend . CI i ck 
Dim mm As New Mai 1 Message( ) 
Dim mattach As Mai lAttachment 
Dim fileTitle As String 
Dim aPos As Integer 

' set the MailMessage properties 

mm. To - txtTo.Text 

mm. From - txtFrom.Text 

mm. Subject = txtSubject.Text 

mm. Body = txtMessage.Text 

' get the attachment, if present 
If Not IsNothing _ 

( txtAttachment . PostedFi 1 e) Then 
' get the file title without the path 
fileTitle = txtAttachment. 

PostedFile. FileName 
fileTitle = f i 1 eTi tl e . Substri ng 

(fileTitle. LastlndexOf ( "\" ) + 1) 
' save the posted file 
txtAttachment. Posted File. SaveAs _ 

("c:\temp\" & fileTitle) 
' create a Mai lAttachment object 
mattach = New MailAttachment 

("c:\temp\" & fileTitle) 
' add the attachment to the MailMessage 
mm. Attachments .Add (mattach) 
' delete the temporary file 
System. 10. File. Delete 

("c:\temp" 8, fileTitle) 
End If 

SmtpMai 1 .Send(mm) 
End Sub 



Listing 2 This alteration of the btnSend_Click event code sends a 
message with an attachment, if one is present. It retrieves the up- 
loaded file data from the HtmlFilelnput control's PostedFile property 
and saves it to a temporary file on the server. Then it creates a new 
MailMessage object, passing the name of the temporary file as a 
parameter to the MailMessage constructor. 



address doesn't belong to a valid domain. Although the examples 
that accompany this article don't include error traps, you can and 
should trap these errors in production code. 

You aren't limited to sending plain text messages; you can send 
e-mail formatted in HTML too. For example, you can create an 
alternate version of the WebForm that scans the message body for 
HTML tags (see Listing 3). When it finds them, it sends the e-mail 
formatted as HTML; otherwise, it sends the message as plain text. 

Scan Messages for Content 

Other than the added check to see whether the message contains 
HTML, the code is identical to the previous version. However, the 
check serves as an introduction to the power of regular expressions 
in .NET and shows how you might scan messages for specific 
content — perhaps for routing to an appropriate contact. 

The gateway to regular expression matching is the RegEx object, 
which scans a String for pattern matches. You specify the pattern to 
match with an arcane syntax consisting of a string of symbols and 
characters. Forexample, in Listing3, the pattern ("<\w.*>") matches 
any HTML tag, which means the RegEx object matches a character 



I VB.NET (beta 2) • Scan for HTML Tags > 

Private Sub btnSend_Cl ick(ByVal sender _ 
As System. Object, ByVal e As _ 
System. EventArgs ) Handles btnSend.Cl ick 

Dim mm As New MailMessage!) 

Dim mattach As MailAttachment 

Dim fileTitle As String 

Dim aPos As Integer 

Dim rx As Regex 

Dim rxmatch As Match 

mm. To - txtTo.Text 

mm. From - txtFrom.Text 

mm. Subject = txtSubject.Text 

mm. Body = txtMessage.Text 

If Not IsNothingttxtAttachment. _ 
PostedFile) Then 

fileTitle = txtAttachment . PostedFi 1 e. 

Fi 1 eName 
If fileTitle. Length > Then 
fileTitle = f i 1 eTi tl e . Substri ng 

(fileTitle. Last IndexOf ( " \" ) + 1) 
txtAttachment . Post edFile. SaveAs 

("c:\temp\" & fileTitle) 
mattach = New MailAttachment 

("c:\temp\" & fileTitle) 
mm. Attachments. Add (mattach) 
System. 10. Fi le. Del ete( "c: \temp" & 
fileTitle) 
End If 
End If 

rx - New Regext "<\w.*>" ) 
rxmatch = rx.Match(mm.Body) 
If rxmatch . Success Then 

mm.BodyFormat = Mai 1 Format . Html 

Else 

mm.BodyFormat = Mai 1 Format .Text 
End If 

SmtpMai 1 . Send(mm) 
End Sub 



Listing 3 This altered version of the btnSend_Click event code checks 
to see if the message body submitted by the user contains at least 
one HTML tag. If so, it sends an HTML-formatted message; other- 
wise, it sends a plain text message. 
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Figure 2 Change the Value Manually. When you place an HtmllnputFile control on the 
WebForm design surface, Visual Studio disables the runat property. However, you can change 
the value manually by clicking on the HTML tab at the bottom of the design window to 
access the HTML content (see Listing 3). 



pattern that begins with a left angle bracket 
followed by any word character (\w, which 
matches a-z, A-Z, or 0-9), followed by or 
more additional characters of any type (.*), 
and finishes with a right angle bracket. The 
pattern shown in this simple example won't 
match a VB not-equal symbol (<>) or angle 
brackets that enclose only white space, but it 
is by no means robust enough for produc- 
tion-quality code; for example, the pattern 
shown matches XML tags and invalid 
HTML tags as well as valid HTML tags. 
Rather than trying to determine the content 
type automatically, most e-mail programs 
let users select whether they want to send 
messages as HTML or text. 

The RegEx object returns a Match object. 
The Match. Success property has a value of 
True if any matches occurred. The Match 
object contains far more information than a 
simple Boolean value, but this example doesn' t 
need any advanced Match object functional- 
ity — the WebForm sends the message as 
HTML if any match occurs. Use the 
MailMessage object's BodyFormat property 
to control the format. The BodyFormat prop- 
erty accepts one of two enumeration values: 
MailFormat.Html or MailFormat.Text. 

In the future, the .NET Framework will 
undoubtedly be able to send e-mail mes- 
sages in other ways, but right now, it's 
enough that sending mail is finally both 
simple and built into the framework. 
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Save Application 
Preferences 



Say goodbye to INI files and Registry settings. Use classes to save users' 
preferences to your database. 




□ VB.NET 

□ C# 

STSQL Server 2000 

□ ASP .NET 

□ XML 
£fVB6 
Ef Other: 

ActiveX Data Objects 
(ADO) 2.5 



Users like your apps to remember their prefer- 
ences — for example, which items they last se- 
lected in a listbox control or the widths of the col- 
umns in a grid. This means you not only have to write 
the code to save and retrieve these preferences, but 
you need to figure out where to store this informa- 
tion. In this column, I'll show you how to use SQL 
Server to store user preference data (you can also 
modify this approach easily to work with any SQL 
database). This method is scalable: It works well for 
small, client/server applications as well as large ones. 

Earlier versions of Windows used INI files to save 
preferences. Now the Registry is generally the pre- 
ferred location for storing user settings, but it has 
some drawbacks. You can use the Visual Basic 
SaveSetting command and the GetSetting function 
for saving and retrieving Registry entries. However, 
the Registry saves preferences locally, so if users get a 



by Dianne Siebold 

new computer, their preferences are gone and they 
have to save them all over again. 

There's a better way to save your application's user 
preferences to a database: Use two simple classes that 
handle saving and retrieving the preferences. There's 
no limitation to the number and types of settings your 
application can save because the data is stored in a 
table. I'll show you the architecture used to save and 
retrieve user preferences and how to implement it. 
The sample application demonstrates how to use 
these classes by saving and loading both the items 
selected in a listbox, and the width of columns in a 
grid (download the code from the VSM Web site; see 
the Go Online box for details). 

There are several benefits to saving user settings to 
a database. All user settings are saved centrally, so you 
need to make administrative changes only in one 
location instead of at each user's computer. Prefer- 
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Figure 1 Store Preferences in the UserPreference Table. You need three tables to implement saving prefer- 
ences to a database. The UserPreference table contains each user's preferences. This table has a foreign key to 
the PreferenceType table and the Employee table. 
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ences are global: They're available to users no matter which com- 
puter they use to run your application. This approach is also 
scalable. It works in a simple client/server environment, as well as a 
distributed environment. User preferences are backed up regularly 
with the database, there's no limitation to the number and type of 
user preferences you can save, and you can use this approach with 
any database. 

Create the Classes 

You'll take a bottom-up approach to creating this application, so 
start by looking at how to store the user preferences in the database. 
Add three tables to your database by running the SQL code in the 
readme.txt file in the sample app: Employee, UserPreference, and 
PreferenceType. The primary table is UserPreference, which stores 
each user's preference values (see Figure 1). This table has a foreign 
key to the Employee table on the EmployeelD column and a foreign 
key to the PreferenceType table on the PreferenceTypelD col- 
umn. A column of Text data type stores the data that makes up the 
preferences. The SQL code also adds some data to the Employee 
and PreferenceType tables and adds a stored procedure to the 
current database. 

Take a look at the classes in the test project. The UPPref- 
erences.Prefs class can be client-side or Microsoft Transaction 
Server (MTS)/COM+, and it handles the database interaction of 
saving and retrieving the preferences. To enable this class to run in 
MTS or COM+, you need to set the MTSTransactionMode 
property to a value greater than No Transactions and put the 
appropriate SetCommit and SetAbort statements in the methods. 
The client passes the preferences into the Prefs class in a recordset 
designed to be marshaled efficiently. 

The second class, called UPPropertyBag, is a generic client-side 
object that handles parsing the various elements of the preferences. 
This property bag object is similar to the VB property bag, but with 
some improvements. For example, the property bag passes its 
contents as a string instead of a byte array. Each element or 
preference in the string has a key and a value, so the grid width 
preferences for each column look like this: 

" Col umnO "" 900 "" Col umnl" 1200 ""Col umn2" 
"700" 

Just like the VB property bag, the WriteProperty method saves 
values to the property bag, and the ReadProperty method retrieves 
them. The Contents property gets and sets the property bag 
contents, which the client passes as a string (unlike the VB property 
bag, which requires them as a byte array). 

Take a look at how these objects work together to retrieve and 



VB6 • GetUserPreferences 
ingle User's Pre 

- — 

Private Function GetUserPref erences ( ) As Boolean 

Dim PrefsRS As AD0DB. Recordset 

Dim AppPropertyBag As UPPropertyBag . PropertyBag 

'The preferences for this user are returned in 
'a recordset. 

If Not mPref erences . GetUserPreferences _ 
(mEmployeelD, PrefsRS) Then Exit Function 

'Loop through the recordset and save each 
'preference in its own property bag. 
PrefsRS. MoveFirst 
Do Until PrefsRS. EOF 

Set AppPropertyBag = New _ 

UPPropertyBag. Property Bag 
If Not IsNull 

( PrefsRS ( " Pref erenceText " ) . Val ue) Then 
AppPropertyBag. Contents = _ 
PrefsRS( " Pref erenceText" ) 
End If 

'Add each property bag to a form-level 

' col 1 ecti on . 

mUserPreferences .Add AppPropertyBag, _ 
CStr( Prefs RS( "DescPreferenceType" ) ) 



Set AppPropertyBag 
PrefsRS. MoveNext 
Loop 



Nothi ng 



GetUserPreferences = True 
End Function 



Listing 1 The GetUserPreferences function calls a method of the 
same name to return the preferences for a single user in a recordset. 
The function then adds the preferences to a property bag, and stores 
each property bag object in a collection. 

save settings in a user interface. The test application has a grid and 
a listbox. You want to save the items the user last selected in the 
listbox and the widths of the grid columns, so when users open this 
form, their previous settings are loaded. The Form_Load event 
makes a call to a function called GetUserPreferences and retrieves all 
the preferences for the specified user with this query: 

SELECT up. EmployeelD. pt.ID 
PreferenceTypelD. 

pt . Descri ption DescPreferenceType , 

up . PreferenceText 
FROM PreferenceType pt 



Load preferences 







UPPropertyBag. Property. Bag class UPPreferences. Prefs class 



Figure 2 Save User Preferences. Instead of saving program settings to individual users' machines, this approach saves them to the data- 
base using the UPPropertyBag. PropertyBag and UPPreferences. Prefs classes. 
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LEFT OUTER JOIN UserPref erence up 
ON up . Pref erenceTypelD = pt.ID AND 
.up.EmployeelD = 108 
LEFT OUTER JOIN Employee e ON 

e.EmployeelD - up.EmployeelD 
AND e.EmployeelD = 108 

Notice that the query selects from the PreferenceType table and has 
an outer join to the UserPreference table. This creates a recordset 
that contains a row for each preference type and the user's prefer- 
ences for that type, if there are any. The client saves the preference 
types that a user has previously saved preferences for into property 
bag objects and adds them to a form-level collection called 
mUserPreferences (see Listing 1). You access a particular property 
bag by creating a form-level variable for a specific bag, then setting 
it to the appropriate bag in the mUserPreferences collection using 
the preference type description: 

Private mGri dPref sBag As _ 
UPPropertyBag . Property Bag 

Set mGridPref sBag = mUserPreferences _ 
( "Test Form. Gri dPref erences" ) 

Now that you have a reference to the grid preferences property 
bag, use it to set the grid column widths to the same values as the last 
time the user opened this form. Do this by using the ReadProperty 
method to query the values from the mGridPrefs property bag (see 
Listing 2). 

Save Screen Settings 

The code that saves the preferences works in reverse order and 
saves the user preferences to the property bag first (see Figure 2). 
Using the grid preferences as an example, the code in the 
Form_Unload event loops through each column in the grid and 
writes the column widths to the property bag. The key for each 

(~ VB6 • Set the Width ~A 

'Sets the column widths of the grid columns 
'based on what was previously selected. 
Private Function LoadGridPrefst ) As Boolean 

On Error GoTo ErrorHandler 

Dim i As Integer 

For i - To (MSFlexGridl.Cols - 1) 
MSFlexGridl.ColWidth(i) = _ 

mGridPrefsBag.ReadPropertyCColumn" & CStr(i)) 
Next i 

Exit Function 
ErrorHandl er : 

End Function 



Listing 2 This function loops through each column in the grid and 
sets the width to what the user selected previously. The function 
does this by calling the ReadProperty method on the property bag 
and passing the key of the desired value — in this case, the word 
"Column" with the column index appended to it. 



value is the string "Column" plus the index of the column 
(ColumnO, Columnl, and so on): 

For i = To (MSFlexGridl.Cols - 1) 
mGridPrefsBag.WriteProperty _ 
"Column" & CStr(i ) , CStr _ 
(MSFlexGridl.ColWidth(i))l 

Next i 

SaveUser Pref erences 

Once you save the values in the property bag, the SaveUserPreferences 
function saves them to a recordset (download Listing 3). The Save- 
UserPreferences function then passes this recordset into the Prefs 
class's SaveUserPreferences method, where it saves the preferences 
for this user to the UserPreference table. The stored procedure 
checks to see if the specified user has a record for the preference type 
already. If so, it's updated; if not, a new record is inserted. 

This is where this method's flexibility comes in. You can save 
preferences in two different ways. First, you can create an entry in 
the PreferenceType table for each control in a screen, which is how 
it's done in the sample application. You have separate entries such 
as TestForm.GridPreferences, TestForm.LisrBoxPreferences, and 
so on. Second, you can save all the preferences for the form's controls 
in a single string. In that case, you have one entry in the Prefer- 
enceType rable (TestForm. Preferences, for example) and one prop- 
erty bag in the application. 

If you need to implement the ability to save user preferences in 
your application, or if you want to move from INI files or Registry 
settings, this might be the solution for you. Not only will this 
method make your job as a developer easier, but the ability to save 
preferences will make your application much more polished and 
professional, uaw 



The code for this article is based on application code written by Cimarron Software 
(www.cimarronsoftware.com). Thanks to Richard Lidstrom and Goran Stijacic for 
letting me use it. 
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programming model provides 
component services across the Web. 



by Bill Wagner 



The Web Services architecture is one the most 
innovative new development technologies in the 
Microsoft .NET Framework. It enables you to build 
components that can deliver their services across the 
Internet to client programs (see the sidebar, "Serving 
Up Web Services"). 

Visual Studio .NET (VS.NET) provides many 
tools to create Web Services — Visual C+ + Developers 
Journal readers learned how to build one using C# 
(see Resources). Here, you'll learn to use ATL Server's 
Web Services tools to build a Web Service using C++. 
You'll also build a C# client to take advantage of the 
Web Service. 

As an example, I'll use data from the U.S. Census 
Bureau (see Resources). This site could really use 



some Web Services! Browse the site and you'll find 
a wealth of collected data in HTML tables or PDF 
files, but you can use the data only as formatted by 
the Census Bureau's Web server, and you can't 
make comparisons or calculations using the data 
directly. Your simple Web Service will deliver sample 
data from the Census Bureau to client applications, 
and your C# client will display this data in a format 
you determine. 

You'll provide three Web methods in your Web 
Service. The simplest, GetStatePopulationO, lets a 
client retrieve the most recent population tally for a 
given state. The second, GetAUPopulationO, lets a 
client retrieve a data structure that contains the most 
recent population numbers for all the states. The 



Serving Up Web Services 



Web Services are a simple concept. A Web Service 
is simply a component that accepts requests deliv- 
ered as XML files using either HTTP or HTTP POST 
commands, and responds to the requests by deliver- 
ing an XML file back to the client. VS.NET provides 
several tools that let you concentrate on your particu- 
lar problem rather than on the transport protocol or 
the XML coding. 

The previous Web application model — a thin 
client model — provided as much computational 
power on the server as possible, with the client 
responsible only for data display. This worked fine 
when the data display was textual, or static. But new 
Web-based applications demand more processing 
to format data and present it. Most users have ample 
processing power on their desktops, but many mod- 
ern applications work with huge amounts of data. It's 
completely unreasonable to expect users to have 
the amount of storage or processor capability asso- 
ciated with large enterprise servers. 

Enter Web Services. Web Services provide a 
mechanism for the server computers and client 



I 



. ^_ 



computers to perform the task each is best suited 
for: Servers can store large amounts of data and do 
computations on them. Clients can execute the best 
presentation for that data and provide a rich environ- 
ment for users. 

You can also use the Web Service model to allow 
two different Web sites to cooperate to provide a 
better user experience. As an example, consider 
online retailers and shipping companies. After you 
place an order, most online retailers provide some 
mechanism for you to query the order status. If your 
order has shipped already, they instead provide you 
with the tracking number and direct you to the 
shipping company's Web site. Once there, you 
enter the tracking number and get the new status 
information. If the shipping company provided a 
Web Service for other Web sites to track ship- 
ments, the online retailer could send a request to 
the shipping company's Web site to retrieve the 
shipping information as part of the response to your 
query about your order, then present you with all the 
information in one page. 

: 
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third, GetTimeSeriesO, lets a client retrieve all the historical popu- 
lation data from a single state. 

Start VS.NET and select New Project from the File menu, then 
select the Win32 Projects folder from inside the Visual C++ Projects 
Folder. Select ATL Server Web Service Project, and name the 
project "CensusServer" (see Figure 1). Most of the defaults for this 
project are correct. I find it easier to build a combined DLL for an 
ATL Web Service, so go to the Project Settings tab and check the 
Generate Combined DLL box for simpler deployment. Your project 
creates one DLL that holds the ISAPI extension and the Web 
Service; it creates two separate DLLs when this box is unchecked. 

Now define the interface, ICensusServerService, for the three 
methods you'll implement. The ATL Server AppWizard provides 
boilerplate code that includes the canonical "Hello World" Web 
Service method; you'll remove this code and go through a two-step 
process to add the interface definition for the CensusServer methods 
(see Listing 1). First, provide the structures for the nodes retrieved 
when a client asks for multiple data points. These structures define 
the XML nodes the Web Service returns as part of the methods. The 
first node defines a state identifier and a population; the second, a 
year and a population. 

Second, define the GetStatePopulation(), GerAllPopulation(), 
and GetTimeSeriesO Web Service methods. Add the first method's 
definition to your sample now (see Listing 2) — you'll add the next 
two methods later. 

If this were a production Web Service connected to real Census 
data, the method implementation would use a large database to find 
the answers. This is a sample application, so you'll add code to store 
the information this service provides. Use a C++ standard library 
map to store the state/population pairs by adding the necessary 
includes at the top of the CensusServer.h file: 

^include <map> 
#include <string> 
using namespace std; 

Next, add member variable declarations to store the map be- 
tween state abbreviations and populations: 

private: 

static map <string. long > 
CurrentPopulationStats; 

Finally, add a constructor to initialize this data stt ucture with the 
information containing the pertinent data. Download the code from 
the KSMWeb site to see the boilerplate code that fills the map (see the 
Go Online box for details). Finally, add the method implementation 
for the GetStatePopulationO Web Service method (see Listing 2). 
Now build the service and run it to display its Web Service contract, 
a description that lets client programs build proxies to communicate 
with it (see Figure 2). 

Build the Client 

Next, build a client to use this new Web Service — call it Census 
Client. Select New Project from the File menu, then choose C# 
Windows Application. Add the client application to the current 



Figure 1 Create an ATL Server Web Service. VS.NET makes it 
easy to get started with an ATL Server Web Service. It creates the 
Web Application and ISAPI Extension DLLs, and even adds deploy- 
ment support. 

f VC++.NET • Define the Web Service Interface ^\ 



Listing 1 This code defines the CensusServer Web Service interface, 
which contains two node definitions and three methods. The compiler 
uses the attributes to produce the type library for the Web Service. 



// The XML Node for a state/population pair 

[ export ] 

struct StatePopul ati on I 
BSTR state; 
int population; 

); 

// The XML Node for a point in the time series 

[ export ] 

struct YearPopul ation ( 
int year; 
int population: 

I; 

// ICensusServerService - Web service 
// interface declaration 

// 
[ 

uuid( "5C346C5D-54FD-471E-81FE-5D03551A5010" ) . 

object 

] 

interface ICensusServerService 

1 

[id(D] HRESULT GetStatePopul ati on 

([in] BSTR statelD, [out, retval] long* 
popul ati on ) ; 
[id(2)] HRESULT GetAl 1 Popul ati on 
([in. out] int *count, 
[out , si ze_i s (*count )] StatePopul ati on** 
pStates) ; 

[id(3)] HRESULT GetTi meSeri es ([in] BSTR 

statelD. 
[in, out] int *count, 
[out ,size_is(*count)] YearPopul ation** 

pYears ) ; 

); 
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all the possible Web 



solution to simplify working with both parts of the application. 
First use the Solution Explorer to add a Web Reference to the 
client project so it can access the Web server running your Web 
Service, then add a reference to the Web Service itself. Select Add 
Web Reference from the Project menu, then use the dialog box to 
select the Web server running your service: the "localhost" 
hyperlink, in this case. 

Next, the Add Web Reference wizard shows 
Services running on that host. Choose the "http://localhost/ 
CensusServer/CensusServer.disco" file, which is the "discovery" file 
for the CensusServer Web Service and describes the methods 
available as part of that Web Service. (My one negative comment 
about Web Services: I get a terrible headache from all the punch lines 
trying to escape my brain whenever I think about programming 
with disco files.) Anyway, once you add the Web reference, Census 
Client gets a new class that contains the proxy to access the 
CensusServer Web Service. 

Add controls to the form to test your first interface. Add a 
combo box to pick the state, a button to get the current population, 
and a textbox to display the population (see Figure 3) . Then add the 
code to access the Web Service. First de- 
clare a member variable in the Form object 
for the Web Service proxy, then create the 
object in the Form's constructor: 



VC++.NET • Retrieve a State's Population 



[soap_method] 

HRESULT GetStatePopulationt/* in */ BSTR statelD. 
/* out, retval */ long *population) 

( 

USES_CONVERSION; 

// Convert the BSTR to a standard string: 
const string id = W2CA (statelD); 
map <string, 1 ong> : : i terator i = 

Cur rent Popul ati onStats . f i nd (id); 
if (i != CurrentPopulationStats.end ()) 

*population = i->second; 
else 

return S_FALSE; 
return SJK; 



Listing 2 Implement the Web method that retrieves the current popu- 
lation for a single state. The code searches for the state ID in the data 
structures. If the code finds the state ID after searching for it in the 
data structures, the method returns the current population; other- 
wise, it returns an error 



private localhost.CensusServerService 

cs ; 
cs = new 

localhost.CensusServerServiceO; 

Finally, add a click handler to display the 
population of the selected state: 

protected void buttonl_Cl i ck (object 
sender, System. EventArgs e) 

1 

String s = comboBoxl .Text ; 
int pop = 

cs . GetStatePopul ati on (s); 
textBoxl . Text=pop.ToString( ) ; 



That's all there is to it. Try it yourself: 
Build the project, run it, select a state from 
the combo box, and hit the button. The 
Web Service returns the population. If you 
run in the debugger, you can set breakpoints 
in either the client or the server and walk 
through the code. 

Add the Other Methods 

Now that you've tested the round-trip con- 
nection, add the CensusServer Web Service's 
other two methods: GetAllPopulation() and 
GetTimeSeriesO . Add definitions for the new 
functions in the class definition, as you did 
for GetStatePopulation() . Remember to mark 

100 



<?xml version="1.0" ?> 
- <serviceDescription name= "CensusServerService" 

xmlns:sQ="um:CensusServerService" xmlns="urn:schemas-xmlsoap- 
org:sdl.2000-01-25" targetNamespace= " "> 

- <schema targetNamespace="urn:CensusServerService" 

xmlns="http://www.w3.org/1999/XMLSchema"> 

- <element name="GetStatePopulation "> 

- <complexType> 

-<all> 

<element name="statelD" type="string" /> 

</all> 
</complexType> 
</element> 

- <element name="GetStatePopulationResponse"> 

- <complexType> 

- <all> 

<element name="return" type="int" /> 

</all> 
</complexType> 
</element> 
</schema> 

- <soap xmlns="urn:schemas-xmlsoap-org:soap-sdl-2000-01-25"> 

- <service> 

- <requestResponse name="GetStatePopulation" 

soapAction="#GetStatePopulation"> 
<request ref="sO:GetStatePopulation" /> 
■cresponse ref="sO:GetStatePopulationResponse /> 
</requestResponse> 

- <addresses> 

- <!-- apply to all interactions -> 

oddress uri='http://localhost/CensusServer/ 
CensusServer.dll?Handler=Default" /> 
</addresses> 
</service> 
</soap> 
</serviceDescription> 



Figure 2 View the Service Contract. VS.NET creates a service "contract," or description, 
that lets client programs build proxies to communicate with your Web Service. 
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tsoap_method] 

HRESULT CCensusServer Service: :GetAl 1 Popul ation 
(/*[in,out] */ int *count, 

/* [out,size_is(*count)] */ StatePopul ati on** 
pStates) 

I 

USES_CONVERSION: 

*count = CurrentPopulationStats.size (): 

*pStates = (struct StatePopul ati on*) malloc 
(sizeof (StatePopul ation)*(*count ) ) ; 

map <string, 1 ong> : : i terator i = 

Cur rent Popul ati onStats . begi n ( ) ; 
int index=0; 

while (i !- CurrentPopul ati onStats . end ()) 
I 

(*pStates) [i ndex] . state = SysAl 1 ocStri ng 

(A2W(i ->first.c_str ())); 
(*pStates) [index] .popul ati on = i->second; 

i ndex++: 

) 

return S_0K; 



Listing 3 This code implements GetAIIPopulationO, the Web method 
that retrieves the current population for all states. This method allo- 
cates the storage for the array of nodes and populates each node 
with the necessary data. The count parameter returns the array size; 
the pStates parameter holds the array of nodes. 

each method with the [soap_method] attribute. The functions in the 
sample simply build the data structures to return and send them back 
(see Listing 3 for GetAIIPopulationO ; for GetTimeSeries() , download 
the code from the VSM Web site). Build and run the Web Service. 
Note the Service Definition Language (SDL) file has changed to 
include the new methods you just added. 

Finally, add methods in the client application to test these 
methods. Update the Web reference code in the client project by 
right-clicking on the "localhost" node in the Solution Explorer and 
selecting Update Web Reference. This updates the Web reference 
proxy so it generates code for the new version. 

Next, add a ListView control and two buttons to test the new 
methods (see Figure 4). The code to test these two new methods is 
pretty straightforward. Simply call the service, iterate through the 
results, and add them to the listview (see Listing 3). Clicking on 
either the Get All States or Get Historical Data button fills the 
listview with all the data. The listview's data and column headers 
change depending on which button you push. 

Notice I spent little time discussing the framework necessary to 
create a Web Service using ATL Server — VS.NET's Web Services 
framework does all the grunt work common to all Web Services. 
The framework and code attributes provide all the necessary code to 
turn any class into a Web Service. Simply create the class you want 
with the public methods to implement your interface. 

You should also consider using C# to build your Web Services. I've 
built a Web Service using both C# and VC++.NET. The C# version 
provides higher-level tools, and you can avoid even more of the COM 
plumbing. The CensusServer Web Service doesn't require extensive 
COM programming, but you'll need to think about that when you 
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Figure 3 Consume the Web Service. This simple C# application, 
Census Client, can access the CensusServer Web Service and use 
its results. The user selects a state from the combo box and hits the 
Get Population button to display that state's population. 




Figure 4 Ready, Get Sets, Go! The same C# client application can re- 
trieve sets of data from the Web Service. More sophisticated clients 
could provide sorting and graphing capabilities for data analysis. 

build more complex Web Services. On the VC++.NET side, ATL 
Server lets you use some of the more powerful tools in the C++ 
standard library. If you were to develop this simple Web Service more 
fully, you'd add searching and sorting algorithms to manipulate the 
data. Also, you'd probably use more extensive numerical analysis tools 
to find patterns and trends in the data. You can write these algorithms 
more easily using C++, and consequently, ATL Server. \ 



Bill Wagner is a founder of SRT Solutions (www. 
srtsolutions.com). He has 15 years of programming 
experience and has taught several classes using 
Microsoft development tools. He is writing C# Core 
Language Little Black Book (The Coriolis Group, due out 
in Fall 2001 ). E-mail Bill at wwagner@srtsolutions.com. 
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Look for 
the CVC 
Quality Seal. 



The Component Vendor 
Consortium (CVC) is a non-profit 
organization committed to 
ensuring developers have 
access to well-written, thoroughly 
tested components that can be implemented without difficulty. To help 
you choose components that meet exacting quality standards, the 
Component Vendor Consortium has initiated the CVC Quality Certified 
logo program. This program subjects components to a rigorous series of 
tests, overseen by Compuware Professional Services, an independent 
testing service. To qualify for logo certification, components must achieve 
at least 80% code coverage and must be proven to contain no 
unexplained memory corruption errors, be free of memory leaks, and 
have no unhandled errors or exceptions. When you select a component 
that carries the CVC Quality Certified logo, you can have a feeling of 
confidence, knowing you're using tools designed to keep you 
developing, not trouble shooting. 

For more information on the CVC quality certification process, including 
details on the testing process and procedure, visit the CVC web site at: 

http://www.components.org/quality.asp 
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Put Rich and Thin Together 



Netscape introduced the world's first commercial browser 
in 1994. At that time, local area networks (LANs) were 
really taking off and businesses were connecting their of- 
fices into wide area networks (WANs), sometimes using the 
Internet as an established backbone. The infrastructure existed to 
allow users in any office to connect to the main office at the net- 
work level, but applications still couldn't communicate easily 
over this infrastructure. 

That's when IT professionals realized: Why not build 
browser-based thin clients? Ever since, there has been a tremen- 
dous shift in application development. Browser-based intranet 
applications are now commonplace, but is this a good thing? 
That depends on your needs. 

As an IT professional, you probably think thin clients are great 
because you don't have to deploy anything to the desktop. After 
all, who wants to deal with installation issues, overwritten DLLs, 
and a user out in the middle of nowhere whose machine stopped 
working after he installed the latest version of your Windows app? 
You probably think thin clients are great because they eliminate all 
this hassle and save deployment costs. You're right. 

But talk to a business end user, and you might hear a different 
story. This user probably likes the anywhere, anytime accessibil- 
ity of a Web client, but dislikes the clunky user interface. It's no 
secret: Web UIs are way behind Windows UIs. Developers try to 
overcome this limitation constantly. Many Web applications try 
to offer a rich UI by leveraging IE DHTML features. Others 
make heavy use of ActiveX controls to enhance the user's experi- 
ence. Unfortunately, such measures improve the UI only slightly, 
while taking away some of the deployment benefits. Deploying 
an ActiveX control to the desktop can be every bit as problematic 
as deploying a full-fledged Windows application. In fact, you 
can't deploy any ActiveX controls if the organization's security 
policies are sufficiently strict. 

There's more to the problem than a poor UI. Web applica- 
tions are also difficult to build and can grow into unmanageable 
beasts. This is due largely to the limited capabilities of HTML 
and scripting, which is especially true if you try to make your ap- 
plication browser-independent. Ultimately, developers spend 
more time building a Web application compared to a Windows 
application, with the end result being less than satisfactory for 
the business end user. Clearly something is wrong here. 

With today's technologies, you can build rich Windows ap- 
plications that are easy to deploy, leveraging the Internet or 
intranet for communication with the server. You can also pack- 
age and deploy Visual Basic applications to the desktop over the 




Web. However, the issues of ap- 
plications stepping on each 
other's files remain a problem. 
Windows XP offers a solution to 
deployment issues using mani- 
fest-based, side-by-side deploy- 
ment. You can find a more com- 
plete set of solutions in Windows 
Forms, remoting, and Web Ser- 
vices — all part of .NET. You can 
also build a rich clienr with Win- 
dows Forms and VB.NET, then 
deploy it to the desktop with no 
fear of stepping on another 
application's assemblies. This cli- 
ent can use .NET remoting to 
communicate with your server 
components over HTTP and 
through firewalls. The client calls 
the server components directly, 
so there's no need for a layer of 
HTML forms and Active Server 

Pages to mediate this interaction. Finally, the client can also le- 
verage Web Services to communicate with server applications 
running on any platform and written in any language. 

Deploying the .NET runtime to every desktop is the next big 
hurdle. If you think of the .NET runtime as equivalent to VB6's 
runtime, then deploying a .NET app is no different than deploy- 
ing a VB6 ActiveX control. Speaking practically, however, the 
.NET runtime is much larger than VB6's runtime. There's also 
the small matter that it hasn't been released yet, so there aren't 
many applications that need this runtime at the moment. That 
will change as people realize that installing .NET on every desk- 
top is like installing a browser on every desktop: You install a 
relatively fat client or runtime, then leverage that with thin appli- 
cation clients. With .NET, those thin clients can actually be rich 
Windows apps that are easy to develop and deploy. 



Agree? Disagree? State your 
opinion on the Talk to the 
Editors discussion area on 
The Development Exchange 
(http://news.devx.com) . 

The opinions expressed 
in this editorial are those of 
the author and not neces- 
sarily the opinions of VSM. 



■ Shohoud has been a software developer for more than 12 
years. He writes regularly for Visual Studio Magazine and XML 
Magazine. Yasser is an independent consultant specializing in building 
Web Services with VB and is authoring the book, building Web 
Services with Visual Basic (Addison-Wesley). Reach Yasser at 
www.vbws.com. 
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InterAct 4.0 



Advanced data visualization features, a powerful programming model and ease-of- 
use make InterAct the world's leading COM-based diagramming component. 

With InterAct's seamless integration into Visual Studio tools, professional developers 
can quickly create sophisticated, robust diagram-based applications using our pre- 
built or customizable objects. Take advantage of our Process Automation Engine, 
Layout Manager, Overview Window, printing/print preview and much more, in just a 
few mouse clicks. 

■ NEW Illustrate relationships clearly with List Entities. Programmatically or visually 
build lists of information and link items in lists between List Entity objects. 

■ NEW Get/set the properties of InterAct, the entities and the relations during run-time, 
with the included PropertyBrowser. 

■ Create custom entities easily, at design-time or run-time, including text entities for 
labeling diagrams, and tables in entities for displaying legends and grids of data. 

■ Place images (bitmaps or metafiles) in entities, with transparency option and fill patterns. 

■ Control font, size and color specifications for all entities, relations and diagram attributes. 

■ Provide only the specific objects needed by your user in the custom Tools Palette. 
Custom objects can be added to the Tools Palette or created during run-time, with 
built-in style dialogs. 

■ Coordinate diagram entities with the Layout Manager, with just a mouse-click. 

- Simplify user-navigation of large diagrams, with a zoomable Overview Window that 
synchronizes itself with the viewable portion of the canvas. 



O Curved Relation Styles 

© Set colors and fonts for 
entities and relations 

NEW List Entities 

O Overview Window with 
zoom control 

© Layout Manager and 
custom Tools Palette 

O NEW PropertyBrowser 
control included 

O User-defined Table 
Objects 



For detailed information, visit 
www.infragistics.com 

Download Free Trial Version! 
call 800-231-8588 
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Optimized for OLE DB technology, UltraGrid's unique features and components provide 
more control and flexibility than ever before. We've incorporated truly innovative 
graphical capabilities, giving the developer the ability to simplify navigation through 
complex data structures while providing eye-popping visual appeal. With new printing 
and print preview capabilities, displayed data can look great on paper, too. 



UltraGrid 2.0 Key Features: 

OLE DB bound 

Advanced non-bound modes 

Powerful per-Band data fetching options 

NEW Printing with Print Preview 

Pre-built user interfaces (ViewStyles) for 

flat and hierarchical representation of data 

Programmable objects provide accessibility at every level 

Cell, Row and Header transparency /translucency 

Built-in Masked Editing 

Background images for Grid, Rows, Cells, Headers, and more 

Built-in dropdown calendar 

Multiple Row and Column Scrolling Regions 

Intuitive context-sensitive hierarchical AddRow Bar 

Advanced Custom Property Pages with wizards 

Croup, Column, Row and Cell objects 

Ability for owner-drawn UlElements 

NEW Save and Load Layouts Collection 

Value Lists 

NEW Data Formatting 

Automatic or Manual multi-column sorting of data 
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O ViewStyle multiband 
vertical 

Band Headers and 
Auto Preview Area 

Display images and 
data in cells and 
headers 

O Dropdown calendar 
in grid cell 

© AddNewBox 

© Print Preview Screen 



Seven powerful input components included 
with UltraGrid: ComboBoxEx, Currency, DateEdit, 
DropDownEdit, HotLink, Numeric and Spin. 

Make the most of your investment- 
UltraCrid 2.0 is available with optional 
Subscription Service.* 

For detailed information, visit 
www.infragistics.com 

Download Free Trial Version! 
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nfragistics 

Component powered infrastructure 



Copyright 2001 Infragistics, Inc. All rights reserved. Infragistics, the Infragistics logo, and UltraGrid are trademarks of Infragistics, Inc. All other trademarks or registered trademarks are the respective property of their owners. 



Java 



ActiveX 



.NET 



800-231-8588 infragistics.com 



